forked from mindspore-Ecosystem/mindspore
!27934 fix doc string
Merge pull request !27934 from zhujingxuan/code_docs_scipy
This commit is contained in:
Gitee
commit
bdaa4d5460
|
|
@ -31,21 +31,21 @@ def block_diag(*arrs):
|
|||
Create a block diagonal matrix from provided arrays.
|
||||
|
||||
Given the inputs `A`, `B` and `C`, the output will have these
|
||||
Tensor arranged on the diagonal::
|
||||
Tensors arranged on the diagonal::
|
||||
|
||||
[[A, 0, 0],
|
||||
[0, B, 0],
|
||||
[0, 0, C]]
|
||||
|
||||
Args:
|
||||
A, B, C, ... (Tensor): up to 2-D
|
||||
Input Tensors. A 1-D Tensor or a 2-D Tensor with shape ``(1,n)``.
|
||||
`A`, `B`, `C`, ... (Tensor): up to 2-D Input Tensors.
|
||||
A 1-D Tensor or a 2-D Tensor with shape :math:`(1,n)`.
|
||||
|
||||
Returns:
|
||||
Tensor with `A`, `B`, `C`, ... on the diagonal which has the same dtype as `A`.
|
||||
|
||||
Raises:
|
||||
ValueError: If there are tensors with dimensions higher than 2 in all arguments.
|
||||
ValueError: If there are Tensors with dimensions higher than 2 in all arguments.
|
||||
|
||||
Supported Platforms:
|
||||
``CPU`` ``GPU``
|
||||
|
|
@ -97,7 +97,7 @@ def solve_triangular(A, b, trans=0, lower=False, unit_diagonal=False,
|
|||
|
||||
Args:
|
||||
A (Tensor): A triangular matrix of shape :math:`(N, N)`.
|
||||
b (Tensor): A tensor of shape :math:`(M,)` or :math:`(M, N)`.
|
||||
b (Tensor): A Tensor of shape :math:`(M,)` or :math:`(M, N)`.
|
||||
Right-hand side matrix in :math:`A x = b`.
|
||||
lower (bool, optional): Use only data contained in the lower triangle of `a`.
|
||||
Default is to use upper triangle.
|
||||
|
|
@ -321,31 +321,31 @@ def eigh(a, b=None, lower=True, eigvals_only=False, overwrite_a=False,
|
|||
Solve a standard or generalized eigenvalue problem for a complex
|
||||
Hermitian or real symmetric matrix.
|
||||
|
||||
Find eigenvalues Tensor ``w`` and optionally eigenvectors Tensor ``v`` of Tensor ``a``,
|
||||
where ``b`` is positive definite such that for every eigenvalue λ (i-th entry of w) and
|
||||
its eigenvector ``vi`` (i-th column of``v``) satisfies::
|
||||
Find eigenvalues Tensor `w` and optionally eigenvectors Tensor `v` of Tensor `a`,
|
||||
where `b` is positive definite such that for every eigenvalue `λ` (i-th entry of w) and
|
||||
its eigenvector `vi` (i-th column of `v`) satisfies:
|
||||
a @ vi = λ * b @ vi
|
||||
vi.conj().T @ a @ vi = λ
|
||||
vi.conj().T @ b @ vi = 1
|
||||
In the standard problem, ``b`` is assumed to be the identity matrix.
|
||||
In the standard problem, `b` is assumed to be the identity matrix.
|
||||
|
||||
Args:
|
||||
a (Tensor): A (M, M) complex Hermitian or real symmetric matrix whose eigenvalues and
|
||||
a (Tensor): A :math:`(M, M)` complex Hermitian or real symmetric matrix whose eigenvalues and
|
||||
eigenvectors will be computed.
|
||||
b (Tensor, optional): A (M, M) complex Hermitian or real symmetric definite positive matrix in.
|
||||
b (Tensor, optional): A :math:`(M, M)` complex Hermitian or real symmetric definite positive matrix in.
|
||||
If omitted, identity matrix is assumed.
|
||||
lower (bool, optional): Whether the pertinent Tensor data is taken from the lower or upper
|
||||
triangle of ``a`` and, if applicable, ``b``. (Default: lower)
|
||||
triangle of `a` and, if applicable, `b`. Default: True.
|
||||
eigvals_only (bool, optional): Whether to calculate only eigenvalues and no eigenvectors.
|
||||
(Default: both are calculated)
|
||||
Default: False.
|
||||
_type (int, optional): For the generalized problems, this keyword specifies the problem type
|
||||
to be solved for ``w`` and ``v`` (only takes 1, 2, 3 as possible inputs)::
|
||||
to be solved for `w` and `v` (only takes 1, 2, 3 as possible inputs):
|
||||
1 => a @ v = w @ b @ v
|
||||
2 => a @ b @ v = w @ v
|
||||
3 => b @ a @ v = w @ v
|
||||
This keyword is ignored for standard problems.
|
||||
overwrite_a (bool, optional): Whether to overwrite data in ``a`` (may improve performance). Default is False.
|
||||
overwrite_b (bool, optional): Whether to overwrite data in ``b`` (may improve performance). Default is False.
|
||||
overwrite_a (bool, optional): Whether to overwrite data in `a` (may improve performance). Default: False.
|
||||
overwrite_b (bool, optional): Whether to overwrite data in `b` (may improve performance). Default is False.
|
||||
check_finite (bool, optional): Whether to check that the input matrices contain only finite numbers.
|
||||
Disabling may give a performance gain, but may result in problems (crashes, non-termination)
|
||||
if the inputs do contain infinities or NaNs.
|
||||
|
|
@ -353,13 +353,13 @@ def eigh(a, b=None, lower=True, eigvals_only=False, overwrite_a=False,
|
|||
for generalized eigenvalue problem and if full set of eigenvalues are requested.).
|
||||
Has no significant effect if eigenvectors are not requested.
|
||||
eigvals (tuple, optional): Indexes of the smallest and largest (in ascending order) eigenvalues
|
||||
and corresponding eigenvectors to be returned: 0 <= lo <= hi <= M-1. If omitted, all eigenvalues
|
||||
and corresponding eigenvectors to be returned: :math:`0 <= lo <= hi <= M-1`. If omitted, all eigenvalues
|
||||
and eigenvectors are returned.
|
||||
|
||||
Returns:
|
||||
- Tensor with shape (N,), The N (1<=N<=M) selected eigenvalues, in ascending order,
|
||||
- Tensor with shape :math:`(N,)`, The :math:`N (1<=N<=M)` selected eigenvalues, in ascending order,
|
||||
each repeated according to its multiplicity.
|
||||
- Tensor with shape (M, N), (if ``eigvals_only == False``)
|
||||
- Tensor with shape :math:`(M, N)`, (if :math:`eigvals_only == False`)
|
||||
|
||||
Raises:
|
||||
LinAlgError: If eigenvalue computation does not converge, an error occurred, or b matrix is not
|
||||
|
|
@ -445,20 +445,21 @@ def lu_factor(a, overwrite_a=False, check_finite=True):
|
|||
"""
|
||||
Compute pivoted LU decomposition of a matrix.
|
||||
The decomposition is::
|
||||
.. math::
|
||||
A = P L U
|
||||
where P is a permutation matrix, L lower triangular with unit diagonal elements, and U upper triangular.
|
||||
|
||||
Args:
|
||||
a (Tensor): square matrix of (M, M) to decompose
|
||||
overwrite_a (bool, optional): Whether to overwrite data in A (may increase performance)
|
||||
a (Tensor): square matrix of :math:`(M, M)` to decompose.
|
||||
overwrite_a (bool, optional): Whether to overwrite data in `A` (may increase performance).
|
||||
check_finite (bool, optional): Whether to check that the input matrix contains only finite numbers.
|
||||
Disabling may give a performance gain, but may result in problems
|
||||
(crashes, non-termination) if the inputs do contain infinities or NaNs.
|
||||
|
||||
Returns:
|
||||
Tensor, a square matrix of (N, N) containing U in its upper triangle, and L in its lower triangle.
|
||||
The unit diagonal elements of L are not stored.
|
||||
Tensor, (N,) Pivot indices representing the permutation matrix P:
|
||||
Tensor, a square matrix of :math:`(N, N)` containing `U` in its upper triangle, and `L` in its lower triangle.
|
||||
The unit diagonal elements of `L` are not stored.
|
||||
Tensor, :math:`(N,)` Pivot indices representing the permutation matrix `P`:
|
||||
row i of matrix was interchanged with row piv[i].
|
||||
|
||||
Supported Platforms:
|
||||
|
|
@ -496,8 +497,8 @@ def lu(a, permute_l=False, overwrite_a=False, check_finite=True):
|
|||
diagonal elements, and U upper triangular.
|
||||
|
||||
Args:
|
||||
a (Tensor): a (M, N) matrix to decompose.
|
||||
permute_l (bool, optional): Perform the multiplication P*L (Default: do not permute).
|
||||
a (Tensor): a :math:`(M, N)` matrix to decompose.
|
||||
permute_l (bool, optional): Perform the multiplication :math:`P*L` (Default: do not permute).
|
||||
overwrite_a (bool, optional): Whether to overwrite data in a (may improve performance).
|
||||
check_finite (bool, optional): Whether to check that the input matrix contains
|
||||
only finite numbers. Disabling may give a performance gain, but may result
|
||||
|
|
@ -506,14 +507,14 @@ def lu(a, permute_l=False, overwrite_a=False, check_finite=True):
|
|||
Returns:
|
||||
**(If permute_l == False)**
|
||||
|
||||
- Tensor, (M, M) Permutation matrix.
|
||||
- Tensor, (M, K) Lower triangular or trapezoidal matrix with unit diagonal. K = min(M, N).
|
||||
- Tensor, (K, N) Upper triangular or trapezoidal matrix.
|
||||
- Tensor, :math:`(M, M)` Permutation matrix.
|
||||
- Tensor, :math:`(M, K)` Lower triangular or trapezoidal matrix with unit diagonal. :math:`K = min(M, N)`.
|
||||
- Tensor, :math:`(K, N)` Upper triangular or trapezoidal matrix.
|
||||
|
||||
**(If permute_l == True)**
|
||||
|
||||
- Tensor, (M, K) Permuted L matrix. K = min(M, N).
|
||||
- Tensor, (K, N) Upper triangular or trapezoidal matrix.
|
||||
- Tensor, :math:`(M, K)` Permuted L matrix. :math:`K = min(M, N)`.
|
||||
- Tensor, :math:`(K, N)` Upper triangular or trapezoidal matrix.
|
||||
|
||||
Supported Platforms:
|
||||
``CPU`` ``GPU``
|
||||
|
|
|
|||
|
|
@ -40,10 +40,10 @@ class SolveTriangular(PrimitiveWithInfer):
|
|||
|
||||
Inputs:
|
||||
- **A** (Tensor) - A triangular matrix of shape :math:`(N, N)`.
|
||||
- **b** (Tensor) - A tensor of shape :math:`(M,)` or :math:`(M, N)`. Right-hand side matrix in :math:`A x = b`.
|
||||
- **b** (Tensor) - A Tensor of shape :math:`(M,)` or :math:`(M, N)`. Right-hand side matrix in :math:`A x = b`.
|
||||
|
||||
Returns:
|
||||
- **x** (Tensor) - A tensor of shape :math:`(M,)` or :math:`(M, N)`,
|
||||
- **x** (Tensor) - A Tensor of shape :math:`(M,)` or :math:`(M, N)`,
|
||||
which is the solution to the system :math:`A x = b`.
|
||||
Shape of :math:`x` matches :math:`b`.
|
||||
|
||||
|
|
@ -150,7 +150,7 @@ class CholeskySolver(PrimitiveWithInfer):
|
|||
|
||||
Inputs:
|
||||
- **A** (Tensor) - A matrix of shape :math:`(M, M)` to be decomposed.
|
||||
- **b** (Tensor) - A tensor of shape :math:`(M,)` or :math:`(..., M)`.
|
||||
- **b** (Tensor) - A Tensor of shape :math:`(M,)` or :math:`(..., M)`.
|
||||
Right-hand side matrix in :math:`A x = b`.
|
||||
Returns
|
||||
-------
|
||||
|
|
|
|||
|
|
@ -41,7 +41,7 @@ class _BFGSResults(NamedTuple):
|
|||
search converged, then this is the (local) minimum of the objective
|
||||
function.
|
||||
g_k (Tensor): containing the gradient of the objective function at `x_k`. If
|
||||
the search converged the l2-norm of this tensor should be below the
|
||||
the search converged the l2-norm of this Tensor should be below the
|
||||
tolerance.
|
||||
H_k (Tensor): containing the inverse of the estimated Hessian.
|
||||
old_old_fval (float): Function value for the point preceding x=x_k.
|
||||
|
|
|
|||
|
|
@ -314,10 +314,10 @@ def line_search(f, xk, pk, gfk=None, old_fval=None, old_old_fval=None, c1=1e-4,
|
|||
xk (Tensor): initial guess.
|
||||
pk (Tensor): direction to search in. Assumes the direction is a descent direction.
|
||||
gfk (Tensor): initial value of value_and_gradient as position.
|
||||
old_fval (Tensor): The same as gfk.
|
||||
old_fval (Tensor): The same as `gfk`.
|
||||
old_old_fval (Tensor): unused argument, only for scipy API compliance.
|
||||
c1 (float): Wolfe criteria constant, see ref.
|
||||
c2 (float): The same as c1.
|
||||
c2 (float): The same as `c1`.
|
||||
maxiter (int): maximum number of iterations to search
|
||||
|
||||
Returns:
|
||||
|
|
|
|||
|
|
@ -69,14 +69,14 @@ def minimize(func, x0, args=(), *, method, tol=None, options=None):
|
|||
On GPU, the supported dtypes is float32.
|
||||
|
||||
Args:
|
||||
fun (Callable): the objective function to be minimized, ``fun(x, *args) -> float``,
|
||||
where ``x`` is a 1-D array with shape ``(n,)`` and ``args`` is a tuple
|
||||
fun (Callable): the objective function to be minimized, :math:`fun(x, *args) -> float`,
|
||||
where `x` is a 1-D array with shape :math:`(n,)` and `args` is a tuple
|
||||
of the fixed parameters needed to completely specify the function.
|
||||
``fun`` must support differentiation.
|
||||
x0 (Tensor): initial guess. Array of real elements of size ``(n,)``, where ``n`` is
|
||||
`fun` must support differentiation.
|
||||
x0 (Tensor): initial guess. Array of real elements of size :math:`(n,)`, where `n` is
|
||||
the number of independent variables.
|
||||
args (Tuple): extra arguments passed to the objective function.
|
||||
method (str): solver type. Currently only ``"BFGS"`` is supported.
|
||||
method (str): solver type. Currently only `"BFGS"` is supported.
|
||||
tol (float, optional): tolerance for termination. For detailed control, use solver-specific
|
||||
options.
|
||||
options (Mapping[str, Any], optional): a dictionary of solver options. All methods accept the following
|
||||
|
|
|
|||
|
|
@ -193,17 +193,17 @@ def gmres(A, b, x0=None, *, tol=1e-5, atol=0.0, restart=20, maxiter=None,
|
|||
|
||||
Args:
|
||||
A (Union[Tensor, function]): 2D Tensor or function that calculates the linear
|
||||
map (matrix-vector product) ``Ax`` when called like ``A(x)``.
|
||||
``A`` must return Tensor with the same structure and shape as its argument.
|
||||
map (matrix-vector product) :math:`Ax` when called like :math:`A(x)`.
|
||||
As function, `A` must return Tensor with the same structure and shape as its input matrix.
|
||||
b (Tensor): Right hand side of the linear system representing a single vector.
|
||||
Can be stored as a Tensor
|
||||
Can be stored as a Tensor.
|
||||
x0 (Tensor, optional): Starting guess for the solution. Must have the same structure
|
||||
as ``b``. If this is unspecified, zeroes are used.
|
||||
as `b`. If this is unspecified, zeroes are used.
|
||||
tol (float, optional): Tolerances for convergence,
|
||||
``norm(residual) <= max(tol*norm(b), atol)``. We do not implement SciPy's
|
||||
:math:`norm(residual) <= max(tol*norm(b), atol)`. We do not implement SciPy's
|
||||
"legacy" behavior, so MindSpore's tolerance will differ from SciPy unless you
|
||||
explicitly pass ``atol`` to SciPy's ``gmres``.
|
||||
atol (float, optional): The same as tol.
|
||||
explicitly pass `atol` to SciPy's `gmres`.
|
||||
atol (float, optional): The same as `tol`.
|
||||
restart (integer, optional): Size of the Krylov subspace ("number of iterations")
|
||||
built between restarts. GMRES works by approximating the true solution x as its
|
||||
projection into a Krylov space of this dimension - this parameter
|
||||
|
|
@ -211,11 +211,11 @@ def gmres(A, b, x0=None, *, tol=1e-5, atol=0.0, restart=20, maxiter=None,
|
|||
solution. Larger values increase both number of iterations and iteration
|
||||
cost, but may be necessary for convergence. The algorithm terminates
|
||||
early if convergence is achieved before the full subspace is built.
|
||||
Default is 20.
|
||||
maxiter (integer): Maximum number of times to rebuild the size-``restart``
|
||||
Default: 20.
|
||||
maxiter (int): Maximum number of times to rebuild the size-`restart`
|
||||
Krylov space starting from the solution found at the last iteration. If GMRES
|
||||
halts or is very slow, decreasing this parameter may help.
|
||||
Default is infinite.
|
||||
Default: infinite.
|
||||
M (Union[Tensor, function]): Preconditioner for A. The preconditioner should approximate the
|
||||
inverse of A. Effective preconditioning dramatically improves the
|
||||
rate of convergence, which implies that fewer iterations are needed
|
||||
|
|
@ -229,7 +229,7 @@ def gmres(A, b, x0=None, *, tol=1e-5, atol=0.0, restart=20, maxiter=None,
|
|||
iteration. It does not allow for early termination, but has much less overhead on GPUs.
|
||||
|
||||
Returns:
|
||||
- Tensor, The converged solution. Has the same structure as ``b``.
|
||||
- Tensor, The converged solution. Has the same structure as `b`.
|
||||
- None, Placeholder for convergence information.
|
||||
|
||||
Supported Platforms:
|
||||
|
|
@ -320,11 +320,11 @@ class CG(nn.Cell):
|
|||
def cg(A, b, x0=None, *, tol=1e-5, atol=0.0, maxiter=None, M=None):
|
||||
"""Use Conjugate Gradient iteration to solve ``Ax = b``.
|
||||
|
||||
The numerics of MindSpore's ``cg`` should exact match SciPy's ``cg`` (up to
|
||||
The numerics of MindSpore's `cg` should exact match SciPy's `cg` (up to
|
||||
numerical precision).
|
||||
|
||||
Derivatives of ``cg`` are implemented via implicit differentiation with
|
||||
another ``cg`` solve, rather than by differentiating *through* the solver.
|
||||
Derivatives of `cg` are implemented via implicit differentiation with
|
||||
another `cg` solve, rather than by differentiating *through* the solver.
|
||||
They will be accurate only if both solves converge.
|
||||
|
||||
Note:
|
||||
|
|
@ -333,24 +333,24 @@ def cg(A, b, x0=None, *, tol=1e-5, atol=0.0, maxiter=None, M=None):
|
|||
|
||||
Args:
|
||||
A (Union[Tensor, function]): 2D Tensor or function that calculates the linear
|
||||
map (matrix-vector product) ``Ax`` when called like ``A(x)``.
|
||||
``A`` must return Tensor with the same structure and shape as its argument.
|
||||
map (matrix-vector product) :math:`Ax` when called like :math:`A(x)`.
|
||||
As function, `A` must return Tensor with the same structure and shape as its input matrix.
|
||||
b (Tensor): Right hand side of the linear system representing a single vector. Can be
|
||||
stored as a Tensor.
|
||||
x0 (Tensor): Starting guess for the solution. Must have the same structure as ``b``.
|
||||
tol (float, optional): Tolerances for convergence, ``norm(residual) <= max(tol*norm(b), atol)``.
|
||||
x0 (Tensor): Starting guess for the solution. Must have the same structure as `b`.
|
||||
tol (float, optional): Tolerances for convergence, :math:`norm(residual) <= max(tol*norm(b), atol)`.
|
||||
We do not implement SciPy's "legacy" behavior, so MindSpore's tolerance will
|
||||
differ from SciPy unless you explicitly pass ``atol`` to SciPy's ``cg``.
|
||||
atol (float, optional): The same as tol.
|
||||
differ from SciPy unless you explicitly pass `atol` to SciPy's `cg`.
|
||||
atol (float, optional): The same as `tol`.
|
||||
maxiter (int): Maximum number of iterations. Iteration will stop after maxiter
|
||||
steps even if the specified tolerance has not been achieved.
|
||||
M (Union[Tensor, function]): Preconditioner for A. The preconditioner should approximate the
|
||||
inverse of A. Effective preconditioning dramatically improves the
|
||||
inverse of A. Effective preconditioning dramatically improves the
|
||||
rate of convergence, which implies that fewer iterations are needed
|
||||
to reach a given error tolerance.
|
||||
|
||||
Returns:
|
||||
- Tensor, The converged solution. Has the same structure as ``b``.
|
||||
- Tensor, The converged solution. Has the same structure as `b`.
|
||||
- None, Placeholder for convergence information.
|
||||
|
||||
Supported Platforms:
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ _eps_net = ops.Eps()
|
|||
|
||||
|
||||
def _convert_64_to_32(tensor):
|
||||
"""Convert tensor with float64/int64 types to float32/int32."""
|
||||
"""Convert Tensor with float64/int64 types to float32/int32."""
|
||||
if tensor.dtype == mstype.float64:
|
||||
return tensor.astype("float32")
|
||||
if tensor.dtype == mstype.int64:
|
||||
|
|
|
|||
Loading…
Reference in New Issue