Finalize user guide with plotting (#28)

Author: akaszynski

.github/workflows/ci-build.yml

@@ -33,7 +33,6 @@ jobs:
 
       - name: Install ansys.dpf.core
         run: |
-          pip install ansys.grpc.dpf --extra-index-url https://[email protected]/pyansys/_packaging/pyansys/pypi/simple/
           pip install -r requirements_build.txt
           pip install -e .
           cd tests
@@ -53,7 +52,7 @@ jobs:
 
       - name: Build Documentation
         run: |
-          sudo apt install pandoc -qy
+          sudo apt-get install pandoc -qy
           pip install -r requirements_docs.txt
           make -C docs html
           touch docs/build/html/.nojekyll

.gitignore

@@ -1,6 +1,7 @@
-/__pycache__
-/.pytest_cache
-/.spyproject
+# cache and pyc
+__pycache__
+.pytest_cache
+.spyproject
 
 #tests
 __pycache__

ansys/dpf/core/_version.py

@@ -1,6 +1,6 @@
 """Version for ansys-dpf-core"""
 # major, minor, patch
-version_info = 0, 2, 0
+version_info = 0, 2, 1
 
 # Nice string for the version
 __version__ = '.'.join(map(str, version_info))

ansys/dpf/core/dpf_operator.py

@@ -103,7 +103,23 @@ def connect(self, pin, inpt, pin_out=0):
 
         pin_out : int, optional
             In case of the input is an Operator, this is the output
-            pin of the input Operator.  Defaults to 0
+            pin of the input Operator.  Defaults to 0.
+
+        Examples
+        --------
+        Compute the minimum of displacement by chaining the ``'U'``
+        and ``'min_max_fc'`` operators.
+
+        >>> from ansys.dpf.core import examples
+        >>> data_src = dpf.DataSources(examples.multishells_rst)
+        >>> print(data_src)
+        >>> disp_op = dpf.Operator('U')
+        >>> disp_op.inputs.data_sources(data_src)
+        >>> max_fc_op = dpf.Operator('min_max_fc')
+        >>> max_fc_op.inputs.connect(disp_op.outputs)
+        >>> max_field = max_fc_op.outputs.field_max()
+        >>> max_field.data
+        array([[0.59428386, 0.00201751, 0.0006032 ]])
         """
         request = operator_pb2.UpdateRequest()
         request.op.CopyFrom(self._message)

ansys/dpf/core/errors.py

@@ -12,6 +12,13 @@
 """
 
 
+class LocationError(ValueError):
+    """Raised when using an invalid location"""
+
+    def __init__(self, msg='Invalid location'):
+        ValueError.__init__(self, msg)
+
+
 class ComplexPlottingError(ValueError):
     """Raised when attempting to plot a field with complex data"""
 

ansys/dpf/core/examples/downloads.py

@@ -52,7 +52,7 @@ def _download_file(directory, filename):
     return local_path
 
 ###############################################################################
-# front-facing downloads
+# front-facing functions
 
 def download_transient_result() -> str:
     """Download an example transient result file and return the download path.
@@ -103,7 +103,7 @@ def download_all_kinds_of_complexity() -> str:
 
 
 def download_all_kinds_of_complexity_modal() -> str:
-    """Download an example result file from a static modal analsys and
+    """Download an example result file from a static modal analysis and
     return the download path.
 
     Examples files are downloaded to a persistent cache to avoid
@@ -125,3 +125,28 @@ def download_all_kinds_of_complexity_modal() -> str:
 
     """
     return _download_file('testing', 'modal_allKindOfComplexity.rst')
+
+
+def download_pontoon() -> str:
+    """Download an example result file from a static modal analsys and
+    return the download path.
+
+    Examples files are downloaded to a persistent cache to avoid
+    re-downloading the same file twice.
+
+    Returns
+    -------
+    str
+        Path to the example file.
+
+    Examples
+    --------
+    Download an example result file and return the path of the file
+
+    >>> from ansys.dpf.core import examples
+    >>> path = examples.download_all_kinds_of_complexity_modal
+    >>> path
+    'C:/Users/user/AppData/local/temp/modal_allKindOfComplexity.rst'
+
+    """
+    return _download_file('docs', 'pontoon.rst')

ansys/dpf/core/field.py

@@ -8,6 +8,7 @@
 from ansys.dpf.core.common import natures, types, locations, ShellLayers
 from ansys.dpf.core import operators_helper, scoping, meshed_region, time_freq_support
 from ansys.dpf.core.plotter import Plotter
+from ansys.dpf.core import errors
 
 
 class Field:
@@ -92,9 +93,6 @@ def __init__(self, nentities=0, nature=natures.vector,
 
         self._field_definition = self._load_field_definition()
 
-        # add dynamic methods
-        self._update_dynamic_methods()
-
     @property
     def size(self):
         """Number of elements times the number of components"""
@@ -123,12 +121,6 @@ def elementary_data_shape(self):
         else:
             return self.component_count
 
-    def _update_dynamic_methods(self):
-        """Add or remove dynamic methods to this instance based on the
-        field type"""
-        if self.location in [locations.elemental_nodal, locations.elemental]:
-            self.to_nodal = self.__to_nodal
-
     @property
     def location(self):
         """Return the field location.
@@ -161,8 +153,20 @@ def shell_layers(self):
         if self._field_definition:
             return self._field_definition.shell_layers
 
-    def __to_nodal(self):
-        """create a to_nodal operator and evaluates it"""
+    def to_nodal(self):
+        """Convert this field to one with a Nodal location.
+
+        Only valid when this field's location is ElementalNodal or
+        Elemental.
+
+        Returns
+        -------
+        Field
+            Field with ``location=='Nodal'``.
+        """
+        if self.location == 'Nodal':
+            raise errors.LocationError('Location is already "Nodal"')
+
         op = dpf.core.Operator("to_nodal")
         op.inputs.connect(self)
         return op.outputs.field()

ansys/dpf/core/plotter.py

@@ -195,6 +195,7 @@ def plot_contour(self, field_or_fields_container, notebook=None,
             overall_data[ind] = field.data[mask]
 
         # create the plotter and add the meshes
+        background = kwargs.pop('background', None)
         plotter = pv.Plotter(notebook=notebook, off_screen=off_screen)
 
         # add meshes
@@ -203,6 +204,9 @@ def plot_contour(self, field_or_fields_container, notebook=None,
         kwargs.setdefault('stitle', name)
         plotter.add_mesh(mesh.grid, scalars=overall_data, **kwargs)
 
+        if background is not None:
+            plotter.set_background(background)
+
         # show result
         if show_axes:
             plotter.add_axes()

docs/source/api/field.rst

@@ -1,3 +1,5 @@
+.. _ref_api_field:
+
 ***********
 Field Class
 ***********

docs/source/api/fieldscontainer.rst

@@ -1,3 +1,6 @@
+.. _ref_api_fields_container:
+
+
 *********************
 FieldsContainer Class
 *********************