Merge pull request #18 from pyansys/docs/additional-examples

docs/additional examples

Author: akaszynski

.github/workflows/ci-build.yml

@@ -35,8 +35,7 @@ jobs:
         run: |
           pip install ansys.grpc.dpf --extra-index-url https://[email protected]/pyansys/_packaging/pyansys/pypi/simple/
           pip install -r requirements_build.txt
-          python setup.py bdist_wheel
-          pip install dist/*.whl
+          pip install -e .
           cd tests
           python -c "from ansys.dpf import core; print(core.Report(gpu=False))"
         env:

.gitignore

@@ -40,3 +40,6 @@ docker/v211
 # pytest -coverage
 .coverage
 test-output.xml
+
+# downloaded files
+ansys/dpf/core/examples/_cache/

ansys/dpf/core/__init__.py

@@ -1,3 +1,4 @@
+import inspect
 import os
 import socket
 
@@ -33,6 +34,30 @@
 # solves "QApplication: invalid style override passed, ignoring it."
 os.environ['QT_STYLE_OVERRIDE'] = ''
 
+# Setup data directory
+USER_DATA_PATH = None
+EXAMPLES_PATH = None
+if os.environ.get('DPF_DOCKER', False):  # pragma: no cover
+    # Running DPF within docker (likely for CI)
+    # path must be relative to DPF directory
+    _module_path = os.path.dirname(inspect.getfile(inspect.currentframe()))
+    EXAMPLES_PATH = os.path.join(_module_path, 'examples', '_cache')
+    if not os.path.isdir(EXAMPLES_PATH):
+        os.makedirs(EXAMPLES_PATH)
+
+else:
+    try:
+        import appdirs
+        USER_DATA_PATH = appdirs.user_data_dir('ansys-dpf-core')
+        if not os.path.exists(USER_DATA_PATH):  # pragma: no cover
+            os.makedirs(USER_DATA_PATH)
+
+        EXAMPLES_PATH = os.path.join(USER_DATA_PATH, 'examples')
+        if not os.path.exists(EXAMPLES_PATH):  # pragma: no cover
+            os.makedirs(EXAMPLES_PATH)
+    except:  # pragma: no cover
+        pass
+
 
 # Configure PyVista's ``rcParams`` for dpf
 if module_exists("pyvista"):

ansys/dpf/core/collection.py

@@ -203,8 +203,9 @@ def __getitem__(self, index):
             Entry at the index corresponding to the request.
         """
         self_len = len(self)
-        if index < 0:  # no negative indices
-            index = self_len - index
+        if index < 0:
+            # convert to a positive index
+            index = self_len + index
 
         if not self_len:
             raise IndexError('This collection contains no items')

ansys/dpf/core/data_sources.py

@@ -2,6 +2,7 @@
 
 from ansys import dpf
 from ansys.grpc.dpf import data_sources_pb2, data_sources_pb2_grpc, base_pb2
+from ansys.dpf.core.errors import protect_grpc
 
 
 class DataSources:
@@ -28,7 +29,6 @@ class DataSources:
     Initialize a model from a result path
     >>> import dpf
     >>> dpf.core.DataSources('file.rst')
-
     """
 
     def __init__(self, result_path=None, data_sources=None, channel=None):
@@ -48,6 +48,7 @@ def __init__(self, result_path=None, data_sources=None, channel=None):
         if result_path is not None:
             self.set_result_file_path(result_path)
 
+    @protect_grpc
     def _connect(self):
         """Connect to the grpc service"""
         return data_sources_pb2_grpc.DataSourcesServiceStub(self._channel)
@@ -71,12 +72,6 @@ def set_result_file_path(self, filepath, key=""):
         >>> data_sources = dpf.core.DataSources()
         >>> data_sources.set_result_file_path('/tmp/file.rst')
         """
-        # The filename needs to be a fully qualified file name
-        if not os.path.dirname(filepath):
-            # append local path
-            # TODO: this will not work on a remote server
-            filepath = os.path.join(os.getcwd(), os.path.basename(filepath))
-
         request = data_sources_pb2.UpdateRequest()
         request.result_path = True
         request.key = key
@@ -96,8 +91,8 @@ def add_file_path(self, filepath, key=""):
 
         Examples
         --------
-        >>> import dpf
-        >>> data_sources = dpf.core.DataSources()
+        >>> from ansys.dpf import core as dpf
+        >>> data_sources = dpf.DataSources()
         >>> data_sources.add_file_path('/tmp/ds.dat')
         """
         # The filename needs to be a fully qualified file name
@@ -111,51 +106,48 @@ def add_file_path(self, filepath, key=""):
         request.data_sources.CopyFrom(self._message)
         self._stub.Update(request)
 
-    def add_upstream(self, upstream_data_sources, upstream_id = -2):
+    def add_upstream(self, upstream_data_sources, upstream_id=-2):
         """Add an upstream datasources.
 
-        This is used to add a set of path creating an upstram for recursive workflows.
+        This is used to add a set of path creating an upstram for
+        recursive workflows.
 
         Parameters
         ----------
         datasources : DataSources
 
         """
-        
         request = data_sources_pb2.UpdateUpstreamRequest()
         request.upstream_id = upstream_id
         request.upstream_data_sources.CopyFrom(upstream_data_sources._message)
         request.data_sources.CopyFrom(self._message)
-        self._stub.UpdateUpstream(request)  
+        self._stub.UpdateUpstream(request)
 
     @property
     def result_key(self):
-        info =self.__info__()
-        return info["result_key"]
-    
+        return self._info["result_key"]
+
     @property
     def result_files(self):
-        info =self.__info__()
-        return info["paths"][self.result_key]
-    
-    def __info__(self):
+        return self._info["paths"][self.result_key]
+
+    @property
+    def _info(self):
         list = self._stub.List(self._message)
-        paths ={}
+        paths = {}
         for key in list.paths:
             key_paths=[]
             for path in list.paths[key].paths:
                 key_paths.append(path)
-            paths[key]=key_paths
-        out = {"result_key":list.result_key, "paths":paths}
+            paths[key] = key_paths
+        out = {"result_key": list.result_key, "paths": paths}
         return out
-    
+
     def __str__(self):
-        info =self.__info__()
-        txt = f'DPF data_sources with result key: {self.result_key} \n'
+        info = self._info
+        txt = f'DPF data_sources with result key: {self.result_key}\n'
         txt += f'paths: {info["paths"]}\n'
         return txt
-     
-         
 
     def __del__(self):
         try:  # should silently fail

ansys/dpf/core/dpf_operator.py

@@ -1,4 +1,5 @@
 """Interface to underlying gRPC Operator"""
+from textwrap import wrap
 import logging
 import grpc
 import functools
@@ -11,7 +12,6 @@
 from ansys.dpf.core.inputs import Inputs
 from ansys.dpf.core.outputs import Outputs
 from ansys.dpf.core.mapping_types import map_types_to_python
-from ansys.dpf.core.raw_operators import DPF_HTML_OPERATOR_DOCS
 from ansys.dpf.core.errors import protect_grpc
 
 LOG = logging.getLogger(__name__)
@@ -63,21 +63,17 @@ def __init__(self, name, channel=None):
         self._description = None
         self.inputs = None
         self.outputs = None
-        try:
-            self.__send_init_request()
 
-            # add dynamic inputs
-            if len(self._message.spec.map_input_pin_spec) > 0:
-                self.inputs = Inputs(self._message.spec.map_input_pin_spec, self)
-            if len(self._message.spec.map_output_pin_spec)!=0:
-                self.outputs = Outputs(self._message.spec.map_output_pin_spec, self)
-            self._description = self._message.spec.description
+        self.__send_init_request()
 
-        except grpc.RpcError as e:
-            if e.code() == grpc.StatusCode.INVALID_ARGUMENT:
-                raise ValueError(f'Invalid operator name "{name}"')
+        # add dynamic inputs
+        if len(self._message.spec.map_input_pin_spec) > 0:
+            self.inputs = Inputs(self._message.spec.map_input_pin_spec, self)
+        if len(self._message.spec.map_output_pin_spec) != 0:
+            self.outputs = Outputs(self._message.spec.map_output_pin_spec, self)
+        self._description = self._message.spec.description
 
-    def _add_sub_res_operators(self, sub_results):        
+    def _add_sub_res_operators(self, sub_results):
         """Dynamically add operators instantiating for sub-results.
 
         The new operators subresults are connected to the parent
@@ -218,19 +214,20 @@ def __del__(self):
 
     def __str__(self):
         # return this repr and operator one level up
-        txt = f'DPF "{self.name}" operator\n'
+        txt = f'DPF "{self.name}" Operator\n'
         if self._description:
-            line = [' ','description:', self._description]
-            txt+='{:^3} {:^6} {:^15}'.format(*line)
-            txt+='\n'
+            txt += '    Description:\n'
+            txt += '\n'.join(wrap(self._description, initial_indent='    ',
+                                  subsequent_indent='    '))
+            txt += '\n\n'
         if self.inputs:
-            line = [' ',self.inputs.__str__()]
-            txt+='{:^3} {:^21}'.format(*line)
-            txt+='\n'
+            line = [' ', str(self.inputs)]
+            txt += '{:^3} {:^21}'.format(*line)
+            txt += '\n'
         if self.outputs:
-            line = [' ',self.outputs.__str__()]
-            txt+='{:^3} {:^21}'.format(*line)
-            txt+='\n'
+            line = [' ', str(self.outputs)]
+            txt += '{:^3} {:^21}'.format(*line)
+            txt += '\n'
 
         return txt
 
@@ -257,18 +254,20 @@ def _find_outputs_corresponding_pins(self, type_names, inpt, pin,
             elif python_name == "Any":
                 corresponding_pins.append(pin)
 
+    @protect_grpc
     def _sub_result_op(self, name):
         op = Operator(name)
-        if self.inputs!=None:
+        if self.inputs is not None:
             for key in self.inputs._connected_inputs:
                 inpt = self.inputs._connected_inputs[key]
                 if type(inpt).__name__ == 'dict':
                     for keyout in inpt:
                         op.connect(key,inpt[keyout],keyout)
-                else :
+                else:
                     op.connect(key,inpt)
         return op
 
+    @protect_grpc
     def __send_init_request(self):
         request = operator_pb2.OperatorName()
         request.name = self.name
@@ -277,12 +276,12 @@ def __send_init_request(self):
     def __mul__(self, inpt):
         if isinstance(inpt, Operator):
             op = Operator("dot")
-            op.connect(0,self,0)  
-            op.connect(1,inpt,0)            
+            op.connect(0, self, 0)
+            op.connect(1, inpt, 0)
         elif isinstance(inpt, float):
             op = Operator("scale")
-            op.connect(0,self,0)  
-            op.connect(1,inpt)
+            op.connect(0, self, 0)
+            op.connect(1, inpt)
         return op
 
     def __truediv__(self, inpt):

ansys/dpf/core/examples/__init__.py

@@ -1 +1,2 @@
 from .examples import *
+from .downloads import *

ansys/dpf/core/examples/downloads.py

@@ -0,0 +1,56 @@
+"""Download example datasets from https://github.com/pyansys/example-data"""
+import shutil
+import os
+import urllib.request
+
+from ansys.dpf.core import EXAMPLES_PATH
+EXAMPLE_REPO = 'https://github.com/pyansys/example-data/raw/master/result_files/'
+
+
+def delete_downloads():
+    """Delete all downloaded examples to free space or update the files"""
+    shutil.rmtree(EXAMPLES_PATH)
+    os.makedirs(EXAMPLES_PATH)
+
+
+def _get_file_url(directory, filename):
+    return EXAMPLE_REPO + '/'.join([directory, filename])
+
+
+def _retrieve_file(url, filename, directory):
+    """Download a file from a url"""
+    # First check if file has already been downloaded
+    local_path = os.path.join(EXAMPLES_PATH, directory, os.path.basename(filename))
+    local_path_no_zip = local_path.replace('.zip', '')
+    if os.path.isfile(local_path_no_zip) or os.path.isdir(local_path_no_zip):
+        return local_path_no_zip, None
+
+    # grab the correct url retriever
+    urlretrieve = urllib.request.urlretrieve
+
+    dirpath = os.path.dirname(local_path)
+    if not os.path.isdir(dirpath):
+        os.mkdir(dirpath)
+
+    # Perform download
+    _, resp = urlretrieve(url, local_path)
+    return local_path
+
+
+def _download_file(directory, filename):
+    url = _get_file_url(directory, filename)
+    local_path = _retrieve_file(url, filename, directory)
+
+    if os.environ.get('DPF_DOCKER', False):  # pragma: no cover
+        # override path if running on docker as path must be relative
+        # to docker mount
+        local_path = os.path.join('/dpf/ansys/dpf/core/examples/_cache/', directory,
+                                  filename)
+    return local_path
+
+###############################################################################
+# front-facing downloads
+
+def download_transient_result():
+    """Download an example transient result and return the download path"""
+    return _download_file('transient', 'transient.rst')