Add name, array parameters, @ operator to ApdlMath

src/ansys/mapdl/core/math.py

@@ -213,7 +213,7 @@ def vec(self, size=0, dtype=np.double, init=None, name=None, asarray=False):
             else:
                 return ans_vec
 
-    def mat(self, nrow=0, ncol=0, dtype=np.double, init=None, name=None):
+    def mat(self, nrow=0, ncol=0, dtype=np.double, init=None, name=None, asarray=False):
         """Create an APDLMath matrix.
 
         Parameters
@@ -232,6 +232,8 @@ def mat(self, nrow=0, ncol=0, dtype=np.double, init=None, name=None):
             Matrix name.  If given, assigns a MAPDL matrix based on
             the existing named matrix.  Otherwise one will be
             automatically generated.
+        asarray : bool, optional
+            Return a `scipy` array rather than an APDLMath matrix.
 
         Returns
         -------
@@ -262,15 +264,17 @@ def mat(self, nrow=0, ncol=0, dtype=np.double, init=None, name=None):
         else:
             info = self._mapdl._data_info(name)
             if info.objtype == pb_types.DataType.DMAT:
-                return AnsDenseMat(name, self._mapdl)
+                mat = AnsDenseMat(name, self._mapdl)
             elif info.objtype == pb_types.DataType.SMAT:
-                return AnsSparseMat(name, self._mapdl)
+                mat = AnsSparseMat(name, self._mapdl)
             else:  # pragma: no cover
                 raise ValueError(f"Unhandled MAPDL matrix object type {info.objtype}")
 
+        if asarray:
+            mat = mat.asarray()
         return mat
 
-    def zeros(self, nrow, ncol=None, dtype=np.double):
+    def zeros(self, nrow, ncol=None, dtype=np.double, name=None, asarray=False):
         """Create a vector or matrix containing all zeros.
 
         Parameters
@@ -282,6 +286,10 @@ def zeros(self, nrow, ncol=None, dtype=np.double):
         dtype : np.dtype, optional
             Datatype of the vector.  Must be either ``np.int32``,
             ``np.int64``, or ``np.double``.
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
+        asarray : bool, optional
+            Return a `scipy` array rather than an APDLMath matrix.
 
         Returns
         -------
@@ -302,10 +310,10 @@ def zeros(self, nrow, ncol=None, dtype=np.double):
         >>> mat = mm.zeros(10, 10)
         """
         if not ncol:
-            return self.vec(nrow, dtype, init="zeros")
-        return self.mat(nrow, ncol, dtype, init="zeros")
+            return self.vec(nrow, dtype, init="zeros", name=name, asarray=asarray)
+        return self.mat(nrow, ncol, dtype, init="zeros", name=name, asarray=asarray)
 
-    def ones(self, nrow, ncol=None, dtype=np.double):
+    def ones(self, nrow, ncol=None, dtype=np.double, name=None, asarray=False):
         """Create a vector or matrix containing all ones
 
         Parameters
@@ -317,6 +325,10 @@ def ones(self, nrow, ncol=None, dtype=np.double):
         dtype : np.dtype, optional
             Datatype of the vector.  Must be either ``np.int32``,
             ``np.int64``, or ``np.double``.
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
+        asarray : bool, optional
+            Return a `scipy` array rather than an APDLMath matrix.
 
         Returns
         -------
@@ -338,11 +350,11 @@ def ones(self, nrow, ncol=None, dtype=np.double):
         >>> mat = mm.ones(10, 10)
         """
         if not ncol:
-            return self.vec(nrow, dtype, init="ones")
+            return self.vec(nrow, dtype, init="ones", name=name, asarray=asarray)
         else:
-            return self.mat(nrow, ncol, dtype, init="ones")
+            return self.mat(nrow, ncol, dtype, init="ones", name=name, asarray=asarray)
 
-    def rand(self, nrow, ncol=None, dtype=np.double):
+    def rand(self, nrow, ncol=None, dtype=np.double, name=None, asarray=False):
         """Create a vector or matrix containing all random values
 
         Parameters
@@ -354,6 +366,10 @@ def rand(self, nrow, ncol=None, dtype=np.double):
         dtype : np.dtype, optional
             Datatype of the vector.  Must be either ``np.int32``,
             ``np.int64``, or ``np.double``.
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
+        asarray : bool, optional
+            Return a `scipy` array rather than an APDLMath matrix.
 
         Returns
         -------
@@ -375,8 +391,8 @@ def rand(self, nrow, ncol=None, dtype=np.double):
         >>> mat = mm.rand(10, 10)
         """
         if not ncol:
-            return self.vec(nrow, dtype, init="rand")
-        return self.mat(nrow, ncol, dtype, init="rand")
+            return self.vec(nrow, dtype, init="rand", name=name, asarray=asarray)
+        return self.mat(nrow, ncol, dtype, init="rand", name=name, asarray=asarray)
 
     def matrix(self, matrix, name=None, triu=False):
         """Send a scipy matrix or numpy array to MAPDL.
@@ -427,7 +443,12 @@ def matrix(self, matrix, name=None, triu=False):
         return AnsDenseMat(name, self._mapdl)
 
     def load_matrix_from_file(
-        self, dtype=np.double, fname="file.full", mat_id="STIFF", asarray=False
+        self,
+        dtype=np.double,
+        name=None,
+        fname="file.full",
+        mat_id="STIFF",
+        asarray=False,
     ):
         """Import a matrix from an existing FULL file.
 
@@ -439,6 +460,8 @@ def load_matrix_from_file(
             numpy data type. Defaults to ``np.double``.
         fname : str, optional
             Filename to read the matrix from.  Defaults to ``"file.full"``.
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
         mat_id : str, optional
             Matrix type.  Defaults to ``"STIFF"``.
 
@@ -448,7 +471,6 @@ def load_matrix_from_file(
             * ``"GMAT"`` - Constraint equation matrix
             * ``"K_RE"`` - Real part of the stiffness matrix
             * ``"K_IM"`` - Imaginary part of the stiffness matrix
-
         asarray : bool, optional
             Return a ``scipy`` array rather than an APDLMath matrix.
 
@@ -459,7 +481,11 @@ def load_matrix_from_file(
             ``asarray``.
 
         """
-        name = id_generator()
+        if name is None:
+            name = id_generator()
+        elif not isinstance(name, str):
+            raise TypeError("``name`` parameter must be a string")
+
         self._mapdl._log.info(
             "Calling MAPDL to extract the %s matrix from %s", mat_id, fname
         )
@@ -536,7 +562,7 @@ def _load_file(self, fname):
         """
         return load_file(self._mapdl, fname)
 
-    def stiff(self, dtype=np.double, fname="file.full", asarray=False):
+    def stiff(self, dtype=np.double, name=None, fname="file.full", asarray=False):
         """Load the stiffness matrix from a full file.
 
         Parameters
@@ -545,6 +571,8 @@ def stiff(self, dtype=np.double, fname="file.full", asarray=False):
             Numpy data type to store the vector as. Only applicable if
             ``asarray=True``, otherwise the returned matrix contains
             double float numbers. Defaults to ``np.double``
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
         fname : str, optional
             Filename to read the matrix from.
         asarray : bool, optional
@@ -569,9 +597,9 @@ def stiff(self, dtype=np.double, fname="file.full", asarray=False):
             with 1734 stored elements in Compressed Sparse Row format>
         """
         fname = self._load_file(fname)
-        return self.load_matrix_from_file(dtype, fname, "STIFF", asarray)
+        return self.load_matrix_from_file(dtype, name, fname, "STIFF", asarray)
 
-    def mass(self, dtype=np.double, fname="file.full", asarray=False):
+    def mass(self, dtype=np.double, name=None, fname="file.full", asarray=False):
         """Load the mass matrix from a full file.
 
         Parameters
@@ -580,6 +608,8 @@ def mass(self, dtype=np.double, fname="file.full", asarray=False):
             Numpy data type to store the vector as. Only applicable if
             ``asarray=True``, otherwise the returned matrix contains
             double float numbers. Defaults to ``np.double``
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
         fname : str, optional
             Filename to read the matrix from.
         asarray : bool, optional
@@ -605,9 +635,9 @@ def mass(self, dtype=np.double, fname="file.full", asarray=False):
             with 1734 stored elements in Compressed Sparse Row format>
         """
         fname = self._load_file(fname)
-        return self.load_matrix_from_file(dtype, fname, "MASS", asarray)
+        return self.load_matrix_from_file(dtype, name, fname, "MASS", asarray)
 
-    def damp(self, dtype=np.double, fname="file.full", asarray=False):
+    def damp(self, dtype=np.double, name=None, fname="file.full", asarray=False):
         """Load the damping matrix from the full file.
 
         Parameters
@@ -616,6 +646,8 @@ def damp(self, dtype=np.double, fname="file.full", asarray=False):
             Numpy data type to store the vector as. Only applicable if
             ``asarray=True``, otherwise the returned matrix contains
             double float numbers. Defaults to ``np.double``
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
         fname : str, optional
             Filename to read the matrix from.
         asarray : bool, optional
@@ -642,16 +674,20 @@ def damp(self, dtype=np.double, fname="file.full", asarray=False):
 
         """
         fname = self._load_file(fname)
-        return self.load_matrix_from_file(dtype, fname, "DAMP", asarray)
+        return self.load_matrix_from_file(dtype, name, fname, "DAMP", asarray)
 
-    def get_vec(self, dtype=None, fname="file.full", mat_id="RHS", asarray=False):
+    def get_vec(
+        self, dtype=None, name=None, fname="file.full", mat_id="RHS", asarray=False
+    ):
         """Load a vector from a file.
 
         Parameters
         ----------
         dtype : numpy.dtype, optional
             Numpy data type to store the vector as.  Defaults to
             ``np.double``.
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
         fname : str, optional
             Filename to read the vector from.
         mat_id : str, optional
@@ -679,7 +715,11 @@ def get_vec(self, dtype=None, fname="file.full", mat_id="RHS", asarray=False):
         APDLMath Vector Size 126
 
         """
-        name = id_generator()
+        if name is None:
+            name = id_generator()
+        elif not isinstance(name, str):
+            raise TypeError("``name`` parameter must be a string")
+
         self._mapdl._log.info(
             "Call MAPDL to extract the %s vector from the file %s", mat_id, fname
         )
@@ -712,7 +752,7 @@ def set_vec(self, data, name=None):
         data : np.ndarray, list
             Numpy array or Python list to push to MAPDL.  Must be 1
             dimensional.
-        vname : str, optional
+        name : str, optional
             APDLMath vector name.  If unset, one will be automatically
             generated.
 
@@ -735,13 +775,15 @@ def set_vec(self, data, name=None):
         self._set_vec(name, data)
         return AnsVec(name, self._mapdl)
 
-    def rhs(self, dtype=np.double, fname="file.full", asarray=False):
+    def rhs(self, dtype=np.double, name=None, fname="file.full", asarray=False):
         """Return the load vector from a full file.
 
         Parameters
         ----------
         dtype : numpy.dtype, optional
             Data type to store the vector as.  Defaults to ``np.double``.
+        name : str, optional
+            APDLMath matrix name.  Optional and defaults to a random name.
         fname : str, optional
             Filename to read the vector from.  Defaults to ``"file.full"``.
         asarray : bool, optional
@@ -759,7 +801,7 @@ def rhs(self, dtype=np.double, fname="file.full", asarray=False):
 
         """
         fname = self._load_file(fname)
-        return self.get_vec(dtype, fname, "RHS", asarray)
+        return self.get_vec(dtype, name, fname, "RHS", asarray)
 
     def svd(self, mat, thresh="", sig="", v="", **kwargs):
         """Apply an SVD Algorithm on a matrix.
@@ -1263,6 +1305,9 @@ def __sub__(self, op2):
         self._mapdl.run(f"*AXPY,-1,0,{op2.id},1,0,{opout.id}", mute=True)
         return opout
 
+    def __matmul__(self, op):
+        return self.dot(op)
+
     def __iadd__(self, op):
         return self.axpy(op, 1, 1)
 

src/ansys/mapdl/core/xpl.py

@@ -446,7 +446,7 @@ def extract(self, recordname, sets="ALL", asarray=False):  # pragma: no cover
         )
         return self._mapdl.math.mat(dtype=dtype, name=rand_name)
 
-    def read(self, recordname):
+    def read(self, recordname, asarray=False):
         """
         Read a record and return either an APDL math matrix or an APDL math vector.
 
@@ -455,10 +455,17 @@ def read(self, recordname):
         ansys.mapdl.AnsMat or ansys.mapdl.AnsVec
             A handle to the APDLMath object.
 
+        asarray : bool, optional
+            Return a :class:`numpy.ndarray` rather than a :class:`AnsMat
+            <ansys.mapdl.core.math.AnsMat>`. Default ``False``.
+
         Examples
         --------
         >>> vec = xpl.read('MASS')
         >>> vec.asarray()
+        array([ 4,  7, 10, 13, 16, 19, 22, 25, 28, 31, 34, 37, 40, 43,
+               46, 49, 52, 55, 58,  1], dtype=int32)
+        >>> vec = xpl.read('MASS', asarray=True)
         array([ 4,  7, 10, 13, 16, 19, 22, 25, 28, 31, 34, 37, 40, 43,
                46, 49, 52, 55, 58,  1], dtype=int32)
         """
@@ -473,12 +480,16 @@ def read(self, recordname):
 
         # return either vector or matrix type
         if data_info.objtype == mapdl_pb2.DataType.VEC:
-            return self._mapdl.math.vec(dtype=dtype, name=rand_name)
+            out = self._mapdl.math.vec(dtype=dtype, name=rand_name)
         elif data_info.objtype in [mapdl_pb2.DataType.DMAT, mapdl_pb2.DataType.SMAT]:
-            return self._mapdl.math.mat(dtype=dtype, name=rand_name)
+            out = self._mapdl.math.mat(dtype=dtype, name=rand_name)
         else:  # pragma: no cover
             raise ValueError(f"Unhandled MAPDL matrix object type {data_info.objtype}")
 
+        if asarray:
+            out = out.asarray()
+        return out
+
     def write(self, recordname, vecname):
         """
         Write a given record back to an MAPDL file.