Aligning documentation with the other PyAnsys repositories (#77)

Co-authored-by: German <[email protected]>
Co-authored-by: Roberto Pastor Muela <[email protected]>

Author: 3 people

README.rst

@@ -40,6 +40,11 @@ For users
 The ``ansys.math.core`` package currently supports Python 3.7 through
 Python 3.10 on Windows, Mac OS, and Linux.
 
+.. warning:: 
+
+   ``ansys.math.core`` will no longer support Python 3.7 by June 2023.
+
+
 Install the latest package for use with this command:
 
 .. code::
@@ -77,7 +82,7 @@ Verify your installation
 
 Check that you can start PyAnsys Math from Python by running this code:
 
-.. code:: python
+.. code:: python3
 
     import ansys.math.core.math as pymath
 

doc/source/api_ref/index.rst doc/source/api/index.rstdoc/source/api_ref/index.rst renamed to doc/source/api/index.rst

@@ -33,7 +33,7 @@ the NumPy and SciPy linear algebra solvers and the PyAnsys Math solver:
    +--------------------------------------------+-----------------------------------+
    | NumPy and SciPy                            | PyAnsys Math                      |
    +============================================+===================================+
-   | .. code:: python                           | .. code:: python                  |
+   | .. code:: python3                          | .. code:: python3                 |
    |                                            |                                   |
    |   k_py = k + sparse.triu(k, 1).T           |   k = mm.matrix(k_py, triu=True)  |
    |   m_py = m + sparse.triu(m, 1).T           |   m = mm.matrix(m_py, triu=True)  |
@@ -63,7 +63,7 @@ Quick code
 
 Here is a brief example of how you use PyAnsys Math:
 
-.. code:: python
+.. code:: python3
 
     import ansys.math.core.math as pymath
 
@@ -75,7 +75,9 @@ Here is a brief example of how you use PyAnsys Math:
 
     print(w)
 
-.. code:: output
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
 
       UDWZKD :
       Size : 5
@@ -90,6 +92,7 @@ For comprehensive PyAnsys Math examples, see :ref:`ref_pymath_examples`.
    :maxdepth: 1
 
    getting_started/index
-   api_ref/index
+   user_guide/index
+   api/index
    examples/index
    contributing/index

doc/source/api_ref/math.rst doc/source/api/math.rstdoc/source/api_ref/math.rst renamed to doc/source/api/math.rst

@@ -0,0 +1,50 @@
+
+Handling arrays between PyAnsys Math and Python
+===============================================
+
+
+Sending arrays to PyAnsys Math
+------------------------------
+
+.. code:: python3
+
+    import numpy as np
+    import ansys.math.core.math as pymath
+
+    # Start PyAnsys Math as a service.
+    mm = pymath.AnsMath()
+
+    a = np.random.random((2, 3))
+    a_pymath = mm.matrix(a, name="A")
+
+    print(a_pymath)
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+    A: 
+    [1,1]: 4.018e-01 [1,2]: 4.635e-01 [1,3]: 3.682e-01
+    [2,1]: 9.711e-01 [2,2]: 7.601e-02 [2,3]: 8.833e-01
+
+
+
+Transfer a PyAnsys Math matrix to NumPy
+---------------------------------------
+
+.. code:: python3
+
+    a_python = a_pymath.asarray()
+    print((a == a_python).all())
+
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+    True
+
+    
+
+
+    

doc/source/index.rst

@@ -0,0 +1,31 @@
+.. _ref_user_guide:
+
+User guide
+==========
+
+Overview
+--------
+
+You can use the ``AnsMath()`` method to launch an instance of PyAnsys Math.
+
+.. code:: python3
+
+    import ansys.math.core.math as pymath
+
+    # Start PyAnsys Math.
+    mm = pymath.AnsMath()
+    print(mm)
+
+.. rst-class:: sphx-glr-script-out
+
+ .. code-block:: none
+
+    APDLMATH PARAMETER STATUS-  (      0 PARAMETERS DEFINED)
+
+   Name                   Type            Mem. (MB)       Dims            Workspace
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   arrays.rst

doc/source/user_guide/arrays.rst

@@ -1494,8 +1494,20 @@ def dot(self, vec) -> float:
         self._mapdl.run(f"*DOT,{self.id},{vec.id},py_val")
         return self._mapdl.scalar_param("py_val")
 
-    def asarray(self) -> np.ndarray:
-        """Return this vector as a NumPy array.
+    def asarray(self, dtype=None) -> np.ndarray:
+        """Return the vector as a NumPy array.
+
+        Parameters
+        ----------
+        dtype : numpy.dtype, optional
+            NumPy data type to upload the array as. The options are `np.double <numpy.double>`_,
+            `np.int32 <numpy.int32>`_, and `np.int64 <numpy.int64>`_. The default is the current array
+            type.
+
+        Returns
+        -------
+        np.ndarray
+            NumPy array with the defined data type.
 
         Examples
         --------
@@ -1504,8 +1516,12 @@ def asarray(self) -> np.ndarray:
         >>> v = mm.ones(10)
         >>> v.asarray()
         [1. 1. 1. 1. 1. 1. 1. 1. 1. 1.]
+        >>> v.asarray(dtype=np.int32)
+        [1 1 1 1 1 1 1 1 1 1]
+
         """
-        return self._mapdl._vec_data(self.id)
+        vec_data = self._mapdl._vec_data(self.id)
+        return vec_data.astype(dtype) if dtype else vec_data
 
     def __array__(self):
         """Allow NumPy to access this object as if it was an array."""
@@ -1567,7 +1583,7 @@ def sym(self) -> bool:
         return True
 
     def asarray(self, dtype=None) -> np.ndarray:
-        """Return the vector as a NumPy array.
+        """Return the matrix as a NumPy array.
 
         Parameters
         ----------
@@ -1585,11 +1601,11 @@ def asarray(self, dtype=None) -> np.ndarray:
         --------
         >>> import ansys.math.core.math as pymath
         >>> mm = pymath.AnsMath()
-        >>> v = mm.ones(10)
+        >>> v = mm.ones(2,2)
         >>> v.asarray()
-        [1. 1. 1. 1. 1. 1. 1. 1. 1. 1.]
-        >>> v.asarray(dtype=np.int)
-        [1 1 1 1 1 1 1 1 1 1]
+        array([[1., 1.], [1., 1.]])
+        >>> v.asarray(dtype=np.int32)
+        array([[1, 1], [1, 1]])
 
         """
         if dtype: