.. _user_guide_troubleshooting:

===============
Troubleshooting
===============
**故障排除**

本页解释了如何解决使用 PyDPF-Core 时遇到的最常见问题。它还包括改进脚本的建议。

Server issues
-------------
**服务器问题**

Start the DPF server
~~~~~~~~~~~~~~~~~~~~~
**启动 DPF 服务器**

当使用 PyDPF-Core 以 :py:meth:`start_local_server() <ansys.dpf.core.server.start_local_server>` 方法启动服务器时，
或使用 ``Ans.Dpf.Grpc.sh`` 或 ``Ans.Dpf.Grpc.bat`` 文件手动启动服务器时，可能会出现 Python 错误： ``TimeoutError: Server did not start in 10 seconds(超时错误：服务器在 10 秒内未启动)``。
此类错误可能意味着未找到服务器或其依赖项。从 Ansys 统一安装中使用 DPF 时，确保设置了 ``AWP_ROOT{VER}`` 环境变量，其中 ``VER`` 是版本的三位数字格式，如 ``221`` 或 ``222`` 。

Connect to the DPF server
~~~~~~~~~~~~~~~~~~~~~~~~~
**连接 DPF 服务器**

如果在使用 Py-DPF 代码通过 :py:meth:`connect_to_server() <ansys.dpf.core.server.connect_to_server>` 方法
连接到初始化的服务器时出现问题，请确保作为参数设置的 IP 地址和端口号适用于在网络上启动的 DPF 服务器。

Import the ``pydpf-core`` package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**导入 ``pydpf-core`` 软件包**

假设你正在导入 ``PyDPF-Core`` 软件包：

.. code-block:: default

    from ansys.dpf import core as dpf

如果错误列出了缺少的模块，请参阅 :ref:`ref_compatibility`。
对于 ``PyDPF-Core < 0.10.0`` ， `ansys.grpc.dpf <https://pypi.org/project/ansys-grpc-dpf/>`_ 模块应始终与其服务器版本同步。

Model issues
------------

Invalid UTF-8 error
~~~~~~~~~~~~~~~~~~~
**无效的 UTF-8 错误**

假设您正试图访问 :class:`ansys.dpf.core.model.Model` 类。可能会出现以下错误：

.. code-block:: default

    [libprotobuf ERROR C:\.conan\897de8\1\protobuf\src\google\protobuf\wire_format_lite.cc:578] 
    String field 'ansys.api.dpf.result_info.v0.ResultInfoResponse.user_name' contains invalid UTF-8 
    data when serializing a protocol buffer. Use the 'bytes' type if you intend to send raw bytes.

无效的 UTF-8 数据阻止了模型的访问。为避免此错误，请确保您使用的是 0.3.2 或更高版本的 PyDPF-Core。
虽然警告仍会出现，但无效的 UTF-8 数据不应妨碍您使用 :class:`ansys.dpf.core.model.Model` 类。

然后，在结果文件中重现此问题后，可以使用以下方法阻止触发警告：

.. code-block:: default

    from ansys.dpf import core as dpf
    dpf.settings.set_dynamic_available_results_capability(False)
	
但是，前面的代码禁止读取和生成模型的可用结果。将使用模型可用的任何静态结果。

Plotting issues
---------------

在尝试使用 DPF 绘制结果图时，可能会出现以下错误：

.. code-block:: default

    ModuleNotFoundError: No module named 'pyvista'

在这种情况下，只需使用此命令安装 `PyVista <https://pyvista.org/>`_ 即可：

.. code-block:: default

    pip install pyvista

另一种方法是在安装 PyDPF-Core 的同时安装 PyVista。欲了解更多信息，请参阅 :ref:`Install with plotting capabilities<targeto_install_with_plotting_capabilities>` 。

Performance issues
------------------

Get and set a field's data
~~~~~~~~~~~~~~~~~~~~~~~~~~
**获取并设置字段数据**

如果字段大小较大或服务器距离 Python 客户端较远，通过 :py:class:`Field<ansys.dpf.core.field.Field>` 类逐个实体获取或设置字段数据实体可能会很慢。
为提高性能，请在上下文管理器中使用 :py:meth:`as_local_field()<ansys.dpf.core.field.Field.as_local_field>` 方法，将字段数据从服务器带到本地计算机。有关示例，请参阅 :ref:`ref_use_local_data_example` 。

Autocompletion in notebooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**notebooks 自动补全功能**

对于大型模型，Jupyter notebooks 中的自动补全有时会比较慢。
当按下 tab 键时，解释器可能会评估某些属性的获取器。
要禁用此功能，请使用 :py:meth:`disable_interpreter_properties_evaluation() <ansys.dpf.core.settings.disable_interpreter_properties_evaluation>` 方法：

.. code-block:: default

    from ansys.dpf import core as dpf
    dpf.settings.disable_interpreter_properties_evaluation()