Fix failing load array test

.github/workflows/ci.yml

@@ -21,10 +21,10 @@ env:
   # You should go up in number, if you go down (or repeat a previous value)
   # you might end up reusing a previous cache if it haven't been deleted already.
   # It applies 7 days retention policy by default.
-  RESET_PIP_CACHE: 0
-  RESET_EXAMPLES_CACHE: 0
-  RESET_DOC_BUILD_CACHE: 0
-  RESET_AUTOSUMMARY_CACHE: 0
+  RESET_PIP_CACHE: 2
+  RESET_EXAMPLES_CACHE: 2
+  RESET_DOC_BUILD_CACHE: 2
+  RESET_AUTOSUMMARY_CACHE: 2
   PACKAGE_NAME: PyMAPDL
 
 jobs:
@@ -191,9 +191,9 @@ jobs:
         uses: actions/cache@v2
         with:
           path: doc/source/**/_autosummary/*.rst
-          key: autosummary-rst-v{{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }}
+          key: autosummary-v${{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }}
           restore-keys: |
-            autosummary-rst-v{{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}
+            autosummary-v${{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}
 
       - name: Install Docs Build Requirements
         run: |

doc/source/examples/index.rst

@@ -26,6 +26,7 @@ Here are a series of examples using MAPDL with ``ansys-mapdl-core``.
     technology_showcase_examples/techdemo-20/20-example-technology-showcase-dynamic-simulation-PCB
 
 .. include:: technology_showcase_examples/README.txt
+   :start-line: 2
 
 
 .. === EXTENDED EXAMPLES ===
@@ -39,4 +40,5 @@ Here are a series of examples using MAPDL with ``ansys-mapdl-core``.
     extended_examples/Python_UPF/python_upf_examples
 
 .. include:: extended_examples/index.rst
+   :start-line: 2
 

doc/source/user_guide/parameters.rst

@@ -1,3 +1,6 @@
+
+.. _ref_parameters:
+
 *********************************
 Setting and Retrieving Parameters
 *********************************
@@ -42,3 +45,151 @@ ROUT``, you can access it with:
 
 For a full listing of the methods and attributes available to the
 ``Parameters`` class, please reference the :ref:`ref_parameters_api`.
+
+
+
+.. _ref_special_named_param:
+
+Specially Named Parameters
+==========================
+
+Leading Underscored Parameters
+------------------------------
+
+The parameters starting with underscore (``'_'``) are reserved parameters
+for MAPDL macros and routines. Their use is discouraged, and in PyMAPDL
+you cannot set them directly.
+
+If you need to set one of these parameters, you can use
+:attr:`Mapdl._run <ansys.mapdl.core.Mapdl._run>`
+to avoid PyMAPDL parameter name checks. For example
+
+
+.. code:: python
+
+   >>> mapdl._run('_parameter=123')
+   'PARAMETER _PARAMETER =     123.00000000'
+
+By default, this type of parameter cannot be seen when issuing
+:attr:`Mapdl.parameters <ansys.mapdl.core.Mapdl.parameters>`.
+However, you can change this by setting
+:attr:`Mapdl.parameters.show_leading_underscore_parameters 
+<ansys.mapdl.core.Mapdl.parameters.show_leading_underscore_parameters>`
+equal to ``True``.
+For example:
+
+
+.. code:: python
+
+   >>> mapdl.parameters.show_leading_underscore_parameters=True
+   >>> mapdl.parameters
+   MAPDL Parameters
+   ----------------
+   PORT                             : 50053.0
+   _RETURN                          : 0.0
+   _STATUS                          : 0.0
+   _UIQR                            : 17.0
+
+
+Trailing Underscored Parameters
+-------------------------------
+
+Parameters ending with an underscore are recommended for user routines
+and macros.
+You can set this type of parameter in PyMAPDL, but by default,
+they cannot be seen in
+:attr:`Mapdl.parameters <ansys.mapdl.core.Mapdl.parameters>`, unless
+:attr:`Mapdl.parameters.show_trailing_underscore_parameters 
+<ansys.mapdl.core.Mapdl.parameters.show_trailing_underscore_parameters>`
+is set to ``True``.
+
+
+.. code:: python
+
+   >>> mapdl.parameters['param_'] = 1.0
+   >>> mapdl.parameters
+   MAPDL Parameters
+   ----------------
+   >>> mapdl.parameters.show_trailing_underscore_parameters=True
+   >>> mapdl.parameters
+   MAPDL Parameters
+   ----------------
+   PARAM_                           : 1.0
+
+
+Parameters with Leading and Trailing Underscore
+-----------------------------------------------
+
+These are a special type of parameter. They **CANNOT** be seen in :attr:`Mapdl.parameters <ansys.mapdl.core.Mapdl.parameters>` under any circumstances. Their use is not recommended.
+
+You can still retrieve them using any of the normal methods
+to retrieve parameters. But you need to know the parameter name.
+For example:
+
+
+.. code:: python
+
+   >>> mapdl.parameters["_param_"] = 1.0
+   >>> mapdl.parameters
+   MAPDL Parameters
+   ----------------
+   >>> print(mapdl.parameters['_param_'])
+   1.0
+
+
+.. _ref_numpy_arrays_in_mapdl:
+
+
+Issues when Importing and Exporting Numpy Arrays in MAPDL
+=========================================================
+
+Because of the way MAPDL is designed, there is no way to store an
+array where one or more dimension is zero.
+This can happens in Numpy arrays, where its first dimension can be
+set to zero.
+
+.. code:: python
+
+   >>> import numpy
+   >>> from ansys.mapdl.core import launch_mapdl
+   >>> mapdl = launch_mapdl()
+   >>> array40 = np.reshape([1, 2, 3, 4], (4,))
+   >>> array40
+   array([1, 2, 3, 4])
+
+
+These types of array dimensions will be always converted to ``1``.
+For example:
+
+.. code:: python
+
+   >>> mapdl.parameters['mapdlarray40'] = array40
+   >>> mapdl.parameters['mapdlarray40']
+   array([[1.],
+      [2.],
+      [3.],
+      [4.]])
+   >>> mapdl.parameters['mapdlarray40'].shape
+   (4, 1)
+
+This means that when you pass two arrays, one with the second axis equal
+to zero (e.g. ``array40``) and another one with the second axis equal
+to one, if later retrieved, they will have the same
+shape.
+
+.. code:: python
+
+   >>> array41 = np.reshape([1, 2, 3, 4], (4,1))
+   >>> array41
+   array([[1],
+      [2],
+      [3],
+      [4]])
+   >>> mapdl.parameters['mapdlarray41'] = array41
+   >>> mapdl.parameters['mapdlarray41']
+   array([[1.],
+      [2.],
+      [3.],
+      [4.]])
+   >>> np.allclose(mapdl.parameters['mapdlarray40'], mapdl.parameters['mapdlarray41'])
+   True

src/ansys/mapdl/core/mapdl.py

@@ -460,15 +460,15 @@ def _chain_stored(self):
 
     @property
     def parameters(self):
-        """Collection of MAPDL parameters obtainable from the ``*GET`` command or ``GET`` command.
+        """Collection of MAPDL parameters.
 
-        Returns
-        -------
-        :class:`ansys.mapdl.core.parameters.Parameters`
+        Notes
+        -----
+        See :ref:`ref_special_named_param` for additional notes regarding parameter naming in MAPDL.
 
         Examples
         --------
-        Simply list all parameters except for MAPDL MATH parameters
+        Simply list all parameters except for MAPDL MATH parameters.
 
         >>> mapdl.parameters
         ARR                              : ARRAY DIM (3, 1, 1)
@@ -488,16 +488,6 @@ def parameters(self):
         >>> mapdl.parameters['ARR']
         array([1., 2., 3.])
 
-        Get the current routine
-
-        >>> mapdl.parameters.routine
-        'PREP7'
-
-        >>> mapdl.parameters.units
-        'SI'
-
-        >>> mapdl.parameters.csys
-        0
         """
         return self._parameters
 

src/ansys/mapdl/core/parameters.py

@@ -34,73 +34,12 @@
 
 
 class Parameters:
-    """Collection of MAPDL parameters obtainable from the :func:`ansys.mapdl.core.Mapdl.get` command.
+    """Collection of MAPDL parameters.
 
     Notes
     -----
 
-    **Leading underscored parameters**
-
-    The parameters starting with underscore ('_') are reserved parameters
-    for MAPDL macros and routines, therefore its use is discouraged, and
-    in PyMAPDL you cannot set them by default.
-
-    If you need to set one of this parameters, you can use ``mapdl._run``
-    to avoid PyMAPDL parameter name checks. For example
-
-    >>> mapdl._run('_parameter=123')
-    'PARAMETER _PARAMETER =     123.00000000'
-
-    By default, this type of parameters cannot be seen when issuing
-    ``mapdl.parameters``. However, you can change this by setting
-    ``mapdl.parameters.show_leading_underscore_parameters`` equal to True.
-    For example:
-
-    >>> mapdl.parameters.show_leading_underscore_parameters=True
-    >>> mapdl.parameters
-    MAPDL Parameters
-    ----------------
-    PORT                             : 50053.0
-    _RETURN                          : 0.0
-    _STATUS                          : 0.0
-    _UIQR                            : 17.0
-
-
-    **Trailing underscored parameters**
-
-    The parameters ending underscore are recommend for user routines
-    and macros.
-    You can set this type of parameters in PyMAPDL, but by default,
-    they cannot be seen in ``mapdl.parameters``, unless
-    ``mapdl.parameters.show_trailing_underscore_parameters`` is set
-    to True.
-
-    >>> mapdl.parameters['param_'] = 1.0
-    >>> mapdl.parameters
-    MAPDL Parameters
-    ----------------
-    >>> mapdl.parameters.show_trailing_underscore_parameters=True
-    >>> mapdl.parameters
-    MAPDL Parameters
-    ----------------
-    PARAM_                           : 1.0
-
-    **Parameters with leading and trailing underscore**
-
-    These are an especial type of parameters. They CANNOT be seen
-    in ``mapdl.parameters`` under any circumstances, and because
-    of it, it uses is not recommended.
-
-    You can still retrieve them using any of the normal methods
-    to retrieve parameters. But you shall know the parameter name.
-    For example:
-
-    >>> mapdl.parameters["_param_"] = 1.0
-    >>> mapdl.parameters
-    MAPDL Parameters
-    ----------------
-    >>> print(mapdl.parameters['_param_'])
-    1.0
+    See :ref:`ref_parameters` for additional notes.
 
     Examples
     --------
@@ -367,11 +306,6 @@ def __getitem__(self, key):
             raise TypeError("Parameter name must be a string")
         key = key.upper()
 
-        # We are going to directly query the desired parameter.
-        # It is more efficient (less parsing) and
-        # you can obtain leading and trailing underscore parameters, which
-        # they don't appear in a normal ``*STATUS``
-
         with self.full_parameters_output:
             parameters = self._parm
 

tests/test_mapdl.py

@@ -838,8 +838,9 @@ def test_load_array_types(mapdl, array):
     assert np.allclose(mapdl.parameters["myarr"], array, rtol=1e-7)
 
 
-@pytest.mark.parametrize("array", [[1, 3, 10], np.random.randint(1, 20, size=(3,))])
+@pytest.mark.parametrize("array", [[1, 3, 10], np.random.randint(1, 20, size=(5,))])
 def test_load_array_failure_types(mapdl, array):
+    array[0] = array[0] + 1  # This is to avoid having all elements equal #1061
     mapdl.load_array("myarr", array)
     array = np.array(array)
     assert not np.allclose(mapdl.parameters["myarr"], array, rtol=1e-7)