From 6a6f2a943c06e8c401ce0cbf1794ac64fa54fa6e Mon Sep 17 00:00:00 2001 From: moe-ad Date: Tue, 24 Dec 2024 11:47:21 +0100 Subject: [PATCH] doc: modified more files --- src/ansys/dpf/core/common.py | 51 ++++++++++---- src/ansys/dpf/core/config.py | 23 +++--- src/ansys/dpf/core/core.py | 70 ++++++++++--------- src/ansys/dpf/core/custom_container_base.py | 2 +- src/ansys/dpf/core/custom_fields_container.py | 6 +- src/ansys/dpf/core/custom_operator.py | 29 +++++--- src/ansys/dpf/core/custom_type_field.py | 29 +++++--- 7 files changed, 129 insertions(+), 81 deletions(-) diff --git a/src/ansys/dpf/core/common.py b/src/ansys/dpf/core/common.py index 8742132142..ec4f353e90 100644 --- a/src/ansys/dpf/core/common.py +++ b/src/ansys/dpf/core/common.py @@ -21,7 +21,7 @@ # SOFTWARE. """ -Common +Common. .. autoclass:: locations :members: @@ -82,13 +82,7 @@ def __missing__(self, key): class types(Enum): - """ - The ``'types'`` enum contains the available types passed through operators - and workflows to DPF. - - - - """ + """The ``'types'`` enum contains the available types passed through operators and workflows to DPF.""" # Types from grpc proto, do not modify string = 0 @@ -126,6 +120,13 @@ class types(Enum): def types_enum_to_types(): + """Return a mapping of enums and corresponding python or dpf types. + + Returns + ------- + dict + Mapping of enum to the corresponding type. + """ from ansys.dpf.core import ( cyclic_support, data_sources, @@ -185,6 +186,7 @@ def types_enum_to_types(): class natures(Enum): """The ``'natures'`` enum contains the dimensionality types. + It can be used to create a field of a given dimensionality. """ @@ -195,7 +197,9 @@ class natures(Enum): class shell_layers(Enum): - """The ``'shell_layers'`` enum contains the available order of + """Contains data identifying shell layers. + + The ``'shell_layers'`` enum contains the available order of shell layers (or lack of shell layers) that defines how the field's data is ordered. """ @@ -303,6 +307,8 @@ class DefinitionLabels: class TqdmProgressBar(ProgressBarBase): + """Custom progress bar implementation based on tqdm.""" + def __init__(self, text, unit, tot_size=None): import tqdm @@ -322,6 +328,7 @@ def __init__(self, text, unit, tot_size=None): ) def update(self, current_value): + """Modify how the current value of the progress bar is updated.""" if self.tot_size is None: self.bar.total = current_value * 2 self.bar.update(current_value - self.current) @@ -329,6 +336,13 @@ def update(self, current_value): @staticmethod def progress_available(): + """Check if the tdqm module exists. + + Returns + ------- + bool + True if module exists, else False. + """ return module_exists("tqdm") @@ -345,10 +359,10 @@ def _common_percentage_progress_bar(text): class SubClassSmartDict(dict): + """Return the superclass name for a key if not found initially.""" + def __getitem__(self, item): - """If found returns the item of key == ìtem`, else returns item with key matching `issubclass(item, - key)`. - """ + """If found returns the item of key == ìtem`, else returns item with key matching `issubclass(item, key)`.""" if item in self: return super().__getitem__(item) else: @@ -362,6 +376,13 @@ def __getitem__(self, item): def type_to_internal_object_keyword(): + """Return dpf types mapped to internal object keywords. + + Returns + ------- + SubClassSmartDict + Custom dictionary that returns superclass name for a key if not found initially. + """ global _type_to_internal_object_keyword if _type_to_internal_object_keyword is None: from ansys.dpf.core import ( @@ -418,6 +439,7 @@ def type_to_internal_object_keyword(): def type_to_special_dpf_constructors(): + """Return dpf type mapped to special dpf constructors.""" global _type_to_special_dpf_constructors if _type_to_special_dpf_constructors is None: from ansys.dpf.gate.dpf_vector import DPFVectorInt @@ -436,7 +458,7 @@ def type_to_special_dpf_constructors(): def derived_class_name_to_type() -> Dict[str, type]: """ - Returns a mapping of derived class names to their corresponding Python classes. + Return a mapping of derived class names to their corresponding Python classes. Returns ------- @@ -454,7 +476,7 @@ def derived_class_name_to_type() -> Dict[str, type]: def record_derived_class(class_name: str, py_class: type, overwrite: bool = False): """ - Records a new derived class in the mapping of class names to their corresponding Python classes. + Record a new derived class in the mapping of class names to their corresponding Python classes. This function updates the global dictionary that maps derived class names (str) to their corresponding Python class objects (type). If the provided class name already exists in the dictionary, it will either @@ -477,6 +499,7 @@ def record_derived_class(class_name: str, py_class: type, overwrite: bool = Fals def create_dpf_instance(type, internal_obj, server): + """Create a server instance of a given type.""" spe_constructors = type_to_special_dpf_constructors() if type in spe_constructors: return spe_constructors[type](internal_obj, server) diff --git a/src/ansys/dpf/core/config.py b/src/ansys/dpf/core/config.py index 734842d479..74eceb0438 100644 --- a/src/ansys/dpf/core/config.py +++ b/src/ansys/dpf/core/config.py @@ -20,10 +20,7 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -""" -Operator Configuration - -""" +"""Operator Configuration.""" import functools import warnings @@ -222,6 +219,18 @@ def config_option_value(self, config_name): raise KeyError(f"{config_name} option doesn't exist.") def __try_get_option__(self, config_name): + """Return option associated with a given config name. + + Parameters + ---------- + config_name : _type_ + Name of the configuration. + + Returns + ------- + ConfigSpecification + Available configuration options supported by the Operator + """ if self._config_help: if config_name in self._config_help: return self._config_help[config_name] @@ -265,11 +274,6 @@ def config_option_accepted_types(self, config_name): def config_option_default_value(self, config_name): """Retrieve the default value for a configuration option. - Parameters - ---------- - config_name : str - Name of the configuration option. - Returns ------- str @@ -307,6 +311,7 @@ def __str__(self): return _description(self._internal_obj, self._server) def __del__(self): + """Delete this instance of config.""" try: self._deleter_func[0](self._deleter_func[1](self)) except: diff --git a/src/ansys/dpf/core/core.py b/src/ansys/dpf/core/core.py index 39beb3678e..01867c338e 100644 --- a/src/ansys/dpf/core/core.py +++ b/src/ansys/dpf/core/core.py @@ -20,10 +20,7 @@ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE # SOFTWARE. -""" -Core - -""" +"""Core.""" import os import logging @@ -67,6 +64,7 @@ def load_library(filename, name="", symbol="LoadOperators", server=None, generate_operators=False): """Dynamically load an operators library for dpf.core. + Code containing this library's operators is generated in ansys.dpf.core.operators @@ -100,8 +98,7 @@ def load_library(filename, name="", symbol="LoadOperators", server=None, generat def upload_file_in_tmp_folder(file_path, new_file_name=None, server=None): - """Upload a file from the client to the server in a temporary folder - deleted when the server is shutdown + """Upload a file from the client to a temporary server folder deleted on server shutdown. Parameters ---------- @@ -133,8 +130,7 @@ def upload_file_in_tmp_folder(file_path, new_file_name=None, server=None): def upload_files_in_folder( to_server_folder_path, client_folder_path, specific_extension=None, server=None ): - """Upload all the files from a folder of the client - to the target server folder path. + """Upload all the files from a folder of the client to the target server folder path. Parameters ---------- @@ -164,7 +160,7 @@ def upload_files_in_folder( def download_file(server_file_path, to_client_file_path, server=None): - """Download a file from the server to the target client file path + """Download a file from the server to the target client file path. Parameters ---------- @@ -190,8 +186,7 @@ def download_file(server_file_path, to_client_file_path, server=None): def download_files_in_folder( server_folder_path, to_client_folder_path, specific_extension=None, server=None ): - """Download all the files from a folder of the server - to the target client folder path + """Download all the files from a folder of the server to the target client folder path. Parameters ---------- @@ -221,7 +216,7 @@ def download_files_in_folder( def upload_file(file_path, to_server_file_path, server=None): - """Upload a file from the client to the target server file path + """Upload a file from the client to the target server file path. Parameters ---------- @@ -245,8 +240,8 @@ def upload_file(file_path, to_server_file_path, server=None): def make_tmp_dir_server(server=None): - """Create a temporary folder server side. Only one temporary folder can be created - by server instance. + """Create a temporary folder server side. Only one temporary folder can be created by server instance. + The folder will be deleted when the server is stopped. Parameters @@ -265,7 +260,7 @@ def make_tmp_dir_server(server=None): def _description(dpf_entity_message, server=None): - """Ask the server to describe the entity in input + """Ask the server to describe the entity in input. Parameters ---------- @@ -288,7 +283,7 @@ def _description(dpf_entity_message, server=None): def _deep_copy(dpf_entity, server=None): - """Returns a copy of the entity in the requested server + """Return a copy of the entity in the requested server. Parameters ---------- @@ -327,6 +322,7 @@ def _deep_copy(dpf_entity, server=None): class BaseService: """The Base Service class allows to make generic requests to dpf's server. + For example, information about the server can be requested, uploading/downloading file from and to the server can be done, new operators plugins can be loaded... @@ -356,7 +352,7 @@ class BaseService: """ def __init__(self, server=None, load_operators=True, timeout=5): - """Initialize base service""" + """Initialize base service.""" # step 1: get server if server is None: server = server_module.get_or_create_server(server) @@ -376,8 +372,8 @@ def __init__(self, server=None, load_operators=True, timeout=5): self._api.init_data_processing_environment(self) # creates stub when gRPC def make_tmp_dir_server(self): - """Create a temporary folder server side. Only one temporary folder can be created - by server instance. + """Create a temporary folder server side. Only one temporary folder can be created by server instance. + The folder will be deleted when the server is stopped. Returns @@ -392,6 +388,7 @@ def make_tmp_dir_server(self): def load_library(self, file_path, name="", symbol="LoadOperators", generate_operators=False): """Dynamically load an operators library for dpf.core. + Code containing this library's operators is generated in ansys.dpf.core.operators @@ -468,7 +465,8 @@ def __generate_code(TARGET_PATH, filename, name, symbol): @version_requires("6.0") def apply_context(self, context): - """Defines the settings that will be used to load DPF's plugins. + """Define the settings that will be used to load DPF's plugins. + A DPF xml file can be used to list the plugins and set up variables. Parameters @@ -494,7 +492,8 @@ def apply_context(self, context): ) def initialize_with_context(self, context): - """Defines the settings that will be used to initialize DPF. + """Define the settings that will be used to initialize DPF. + A DPF xml file can be used to list the plugins and set up variables. Parameters @@ -531,7 +530,7 @@ def initialize(self): @version_requires("6.0") def release_dpf(self): - """Clears the available Operators and Releases licenses when necessary. + """Clear the available Operators and release licenses when necessary. Notes ----- @@ -544,6 +543,13 @@ def release_dpf(self): @version_requires("4.0") def get_runtime_core_config(self): + """Determine runtime configuration. + + Returns + ------- + RuntimeCoreConfig + Runtime configuration options in DataProcessingCore + """ if self._server().has_client(): data_tree_tmp = self._api.data_processing_get_global_config_as_data_tree_on_client( self._server().client @@ -555,8 +561,7 @@ def get_runtime_core_config(self): @property def server_info(self): - """Send the request for server information and keep - the info into a dictionary + """Send the request for server information and keep the info into a dictionary. Returns ------- @@ -611,7 +616,7 @@ def _get_server_info(self): return out def _description(self, dpf_entity_message): - """Ask the server to describe the entity in input + """Ask the server to describe the entity in input. Parameters ---------- @@ -653,7 +658,7 @@ def _get_separator(self, path): return separator def download_file(self, server_file_path, to_client_file_path): - """Download a file from the server to the target client file path + """Download a file from the server to the target client file path. Parameters ---------- @@ -686,8 +691,7 @@ def _set_collection_api(self): def download_files_in_folder( self, server_folder_path, to_client_folder_path, specific_extension=None ): - """Download all the files from a folder of the server - to the target client folder path + """Download all the files from a folder of the server to the target client folder path. Parameters ---------- @@ -740,8 +744,7 @@ def download_files_in_folder( def upload_files_in_folder( self, to_server_folder_path, client_folder_path, specific_extension=None ): - """Upload all the files from a folder of the client - to the target server folder path. + """Upload all the files from a folder of the client to the target server folder path. Parameters ---------- @@ -822,7 +825,7 @@ def _upload_and_get_server_path( return server_paths def upload_file(self, file_path, to_server_file_path): - """Upload a file from the client to the target server file path + """Upload a file from the client to the target server file path. Parameters ---------- @@ -853,8 +856,7 @@ def upload_file(self, file_path, to_server_file_path): ) def upload_file_in_tmp_folder(self, file_path, new_file_name=None): - """Upload a file from the client to the server in a temporary folder - deleted when the server is shutdown + """Upload a file from the client to a temporary server folder deleted on shutdown. Parameters ---------- @@ -896,7 +898,7 @@ def _prepare_shutdown(self): # @version_requires("4.0") def _release_server(self): """ - Release the reference taken by this client on the server + Release the reference taken by this client on the server. Notes ----- diff --git a/src/ansys/dpf/core/custom_container_base.py b/src/ansys/dpf/core/custom_container_base.py index 1c2201f105..745c3b4130 100644 --- a/src/ansys/dpf/core/custom_container_base.py +++ b/src/ansys/dpf/core/custom_container_base.py @@ -21,7 +21,7 @@ # SOFTWARE. """ -CustomContainerBase +CustomContainerBase. This module contains the `CustomContainerBase` class, which serves as a base for creating wrappers around `GenericDataContainer` objects. diff --git a/src/ansys/dpf/core/custom_fields_container.py b/src/ansys/dpf/core/custom_fields_container.py index c30079efe7..72be15a3de 100644 --- a/src/ansys/dpf/core/custom_fields_container.py +++ b/src/ansys/dpf/core/custom_fields_container.py @@ -21,7 +21,7 @@ # SOFTWARE. """ -Custom Fields Containers +Custom Fields Containers. Contains the inherited classes from the :class:`FieldsContainer ` class. @@ -307,6 +307,7 @@ def __init__(self, fields_container=None, server=None): def get_fields_by_mat_id(self, matid, timeid=None, complexid=None): """Retrieve a list of all fields for a material ID. + You can filter the list of fields for a material ID based on a given time, complex type, or both. @@ -344,6 +345,7 @@ def get_fields_by_mat_id(self, matid, timeid=None, complexid=None): def get_field_by_mat_id(self, matid, timeid=None, complexid=None): """Retrieve a field with a given material ID. + You can filter the field based on a given time, complex type, or both. Parameters @@ -376,7 +378,7 @@ def get_field_by_mat_id(self, matid, timeid=None, complexid=None): return self.get_field(label_space) def get_mat_scoping(self): - """Retrieves the material or body scoping containing material IDs. + """Retrieve the material or body scoping containing material IDs. Returns ------- diff --git a/src/ansys/dpf/core/custom_operator.py b/src/ansys/dpf/core/custom_operator.py index 990f86b6c6..2d67d23005 100644 --- a/src/ansys/dpf/core/custom_operator.py +++ b/src/ansys/dpf/core/custom_operator.py @@ -21,11 +21,12 @@ # SOFTWARE. """ -.. _ref_custom_operator: - -Custom Operator Base +Custom Operator Base. Contains utilities allowing you to implement and record custom Python operators. + +.. _ref_custom_operator: + """ import abc @@ -63,7 +64,7 @@ def update_virtual_environment_for_custom_operators( restore_original: bool = False, ): - """Updates the dpf-site.zip file used to start a venv for Python custom operators to run in. + """Update the dpf-site.zip file used to start a venv for Python custom operators to run in. It updates the site-packages in dpf-site.zip with the site-packages of the current venv. It stores the original dpf-site.zip for future restoration. @@ -221,8 +222,8 @@ def record_operator(operator_type, *args) -> None: class CustomOperatorBase: """ - Base class interfacing CPython Custom Operators which can be used as regular - DPF Operators in any API. + Base class interfacing CPython Custom Operators which can be used as regular DPF Operators in any API. + A CustomOperator is defined by its name, its specification and its run method. These three abstract methods should be implemented to create a CustomOperator. @@ -270,6 +271,7 @@ class CustomOperatorBase: def set_output(self, index: int, data) -> None: """ Add an output to this Operator at the given index. + To use in the ``run`` method. Parameters @@ -293,7 +295,8 @@ def set_output(self, index: int, data) -> None: def get_input(self, index, type: type): """ - Method used to get an input of a requested type at a given index in the ``run`` method. + Get an input of a requested type at a given index in the ``run`` method. + The correct input type must be connected to this Operator beforehand. Parameters @@ -326,6 +329,7 @@ def get_input(self, index, type: type): def set_failed(self) -> None: """ Set the Operator's status to "failed". + To use in the ``run`` method if an error occurred. This "failed" status is automatically set when an exception is raised in the ``run`` method. """ @@ -334,6 +338,7 @@ def set_failed(self) -> None: def set_succeeded(self) -> None: """ Set the Operator's status to "succeeded". + To use at the end of the ``run`` method. """ external_operator_api.external_operator_put_status(self._operator_data, 0) @@ -361,7 +366,8 @@ def _internal_specification(self): @abc.abstractmethod def run(self) -> None: """ - Callback of the Operator to implement. + "Implement the Operator's callback in inheriting subclasses. + The implementation should first request the inputs with the method ``get_input``, compute the output data, then add the outputs with the method ``set_output`` and finally call ``set_succeeded``. @@ -372,8 +378,10 @@ def run(self) -> None: @abc.abstractmethod def specification(self): """ - Documents the operator. The following are mandatory to have a full support - (documentation, code generation and usage) of the new operator: + Documents the operator. + + The following are mandatory to have a full support (documentation, code generation and usage) + of the new operator: * Description * Supported inputs (a name, a document, a list of accepted types (optional) and/or ellipses) * Supported outputs (a name, a document, a type, and can be ellipsis) @@ -391,6 +399,7 @@ def specification(self): def name(self) -> str: """ Returns the identifier or name of the operator. + This name can then be used to instantiate the Operator. """ pass diff --git a/src/ansys/dpf/core/custom_type_field.py b/src/ansys/dpf/core/custom_type_field.py index 3f92c3255f..deb82d426f 100644 --- a/src/ansys/dpf/core/custom_type_field.py +++ b/src/ansys/dpf/core/custom_type_field.py @@ -21,9 +21,9 @@ # SOFTWARE. """ -.. _ref_custom_type_field: +CustomTypeField. -CustomTypeField +.. _ref_custom_type_field: """ @@ -46,7 +46,10 @@ class dict_with_missing_numpy_type(dict): + """Custom dictionary that returns the name attribute of a missing key.""" + def __missing__(self, key): + """Return the name attribute of a missing key.""" return key.name @@ -63,6 +66,7 @@ def __missing__(self, key): class CustomTypeField(_FieldBase): """Represents a simulation data container with each unitary data being of a custom type. + When initializing the ``CustomTypeField`` class, provide a unitary data type. The ``CustomTypeField`` class gives you the ability to choose the most optimized unitary data type for a given usage, and hence, allows you to optimize memory usage. @@ -113,9 +117,7 @@ def __init__( field=None, server=None, ): - """Initialize the field either with an optional field message or - by connecting to a stub. - """ + """Initialize the field either with an optional field message or by connecting to a stub.""" self._server = server_module.get_or_create_server( field._server if isinstance(field, CustomTypeField) else server ) @@ -232,7 +234,7 @@ def location(self, location): self.field_definition = fielddef def is_of_type(self, type_to_compare: np.dtype) -> bool: - """Checks whether the Field's unitary type is the same as the input type. + """Check whether the Field's unitary type is the same as the input type. Parameters ---------- @@ -262,6 +264,7 @@ def is_of_type(self, type_to_compare: np.dtype) -> bool: @property def type(self): """Type of unitary data in the Field's data vector. + Should be properly set at the Field construction to have properly allocated data. Returns @@ -282,14 +285,17 @@ def type(self): @property def component_count(self): + """Number of components.""" return self._api.cscustom_type_field_get_number_of_components(self) @property def elementary_data_count(self): + """Number of elementary data.""" return self._api.cscustom_type_field_get_number_elementary_data(self) @property def size(self): + """Size of data.""" return self._api.cscustom_type_field_get_data_size(self) def _set_scoping(self, scoping): @@ -301,7 +307,7 @@ def _get_scoping(self): return scoping.Scoping(scoping=obj, server=self._server) def get_entity_data(self, index): - """Returns the array corresponding to the data of a given entity index. + """Return the array corresponding to the data of a given entity index. Parameters ---------- @@ -341,7 +347,7 @@ def get_entity_data(self, index): return data def get_entity_data_by_id(self, id): - """Returns the array corresponding to the data of a given entity id. + """Return the array corresponding to the data of a given entity id. Parameters ---------- @@ -384,6 +390,7 @@ def get_entity_data_by_id(self, id): return data def append(self, data, scopingid): + """Append data to the api instance.""" if isinstance(data, list): data = np.array(data, dtype=self._type) self._api.cscustom_type_field_push_back(self, scopingid, _get_size_of_list(data), data) @@ -469,7 +476,7 @@ def unit(self): @unit.setter def unit(self, value): - """Change the unit for the field + """Change the unit for the field. Parameters ---------- @@ -527,8 +534,7 @@ def _set_field_definition(self, field_definition): @property def field_definition(self): - """CustomTypeField information, including its location, unit, dimensionality - and shell layers. + """CustomTypeField information, including its location, unit, dimensionality and shell layers. Returns ------- @@ -546,6 +552,7 @@ def _set_support(self, support): @property def support(self): + """Return the support associated with the custom field.""" obj = self._api.cscustom_type_field_get_support(self) if obj is not None: return Support(support=obj, server=self._server)