PARCEL SYCL v1.2 / API Reference User Guide API Reference Search Download 日本語

20 Python API

From Python, import the package parcel (python/ in the distribution package). The package has its own native layer (libparcel_py.so) that calls the library directly, and is independent of the C and Fortran APIs. The meaning and defaults of the settings, the results, and the convergence states are given in Common Items and Convergence by Solver; the workflow and examples in “Python” in the “Usage” chapter of the User Guide, and installation in “Python Package” in the “Installation” chapter of the User Guide.

20.1 Mapping to the Common Items

The common settings correspond to the arguments of solve() and eigs(), and the results to the attributes of SolveInfo and EigInfo, as follows. Constants are given as strings.

Common setting Argument Expression
Convergence tolerance tol —
Maximum number of iterations maxiter —
Preconditioner type precond "none", "point_jacobi", "block_jacobi", "jacobi"
Number of Jacobi iterations precond_options["iterations"] —
Number of block Jacobi blocks precond_options["blocks"] —
Scaling precond_options["scale_matrix"], ["scale_vector"] True, False, None (automatic)
Restart length (pgmres) restart —
Orthogonalization method (pgmres) orthogonalization "cgs", "mgs"
Basis generation size ss, tt s, t Give both
QR factorization method (pcagmres) qr "cgs", "mgs", "cholesky_qr", "cholesky_qr_moment"
Q mode q_mode "auto", "explicit", "implicit"
Spectrum of the preconditioned matrix precond_spectrum True, False
Type of the inner linear solver inner_method "pgmres", "pcg"
Tolerance of the inner linear solver inner_tol —
Maximum iterations of the inner linear solver inner_maxiter —
Restart length of the inner linear solver inner_restart —
Preconditioner of the inner linear solver inner_precond, inner_precond_options The scaling cannot be specified (always automatic)
Shift-invert sigma Enabled when given. The package assembles A−σIA - \sigma I
Size of the Krylov subspace m, k_keep, nev Give all three
Maximum number of restarts max_restart —
Orthogonalization method (ks_arnoldi) orthogonalization (eigs()) "cgs" (CGS2) or "mgs" (MGS2)
Initial vector v0 —
Common result Attribute
Convergence state converged, reason, reason_code
Iteration count iterations
Residual residual
True residual true_residual
Number of converged eigenpairs n_converged (EigInfo only)
Number of inner solver failures inner_failures (EigInfo only)

20.2 parcel.DistributedCSR

Description Represents the rows owned by this rank of a sparse matrix partitioned into row blocks with MPI (Input Matrix in Common Items).

Synopsis

A = parcel.DistributedCSR(indptr, indices, data, row_start, n_global, comm=None)

Arguments

Name Type Description Default
indptr 1-D integer array 0-based local row pointer of the owned rows (length n_local + 1) —
indices 1-D integer array 0-based global column indices —
data 1-D real array Matrix elements (same length as indices) —
row_start Integer Global row index of the first owned row (0-based) —
n_global Integer Number of global rows —
comm parcel.Comm, mpi4py communicator, None Communicator. None means MPI_COMM_WORLD None

Attributes indptr, indices, data (copied into contiguous int64 / float64 arrays; the original arrays may be modified after the call), row_start, n_global, comm (parcel.Comm), n_local (number of owned rows), nnz (number of nonzeros in the owned rows), shape ((n_global, n_global)).

Requirements The layout is the same as scipy.sparse.csr_matrix. At construction, the following are checked: indptr is a 1-D array of length 2 or more, indices and data are 1-D arrays of the same length, indptr[0] = 0 and indptr[-1] = len(indices); otherwise ValueError is raised. When solving, the following are checked: each rank owns at least one row, indptr is non-decreasing, the column indices are in [0, n_global), and the row blocks of all ranks cover 0 to n_global - 1 without gaps or overlaps (the order of the ranks does not matter); otherwise all ranks raise the same ValueError. If the number of rows exceeds the range of the integers of the native layer, OverflowError is raised.

See Also from_scipy() / from_global(), local_slice()

20.3 DistributedCSR.from_scipy() / DistributedCSR.from_global()

Description Create a DistributedCSR from a SciPy sparse matrix (class methods).

Synopsis

A = parcel.DistributedCSR.from_scipy(local_rows, row_start, n_global=None, comm=None)
A = parcel.DistributedCSR.from_global(global_matrix, comm=None, row_start=None, n_local=None)

Arguments

Name Type Description Default
local_rows scipy.sparse matrix Matrix of the owned rows only (with global columns) —
row_start Integer Global row index of the first owned row. If omitted in from_global(), the decomposition of partition_rows() is used None for from_global()
n_global Integer Number of global rows. If omitted, the number of columns of local_rows None
global_matrix Square scipy.sparse matrix Whole matrix (all ranks hold the same one) —
n_local Integer Number of owned rows (give it together with row_start) None
comm parcel.Comm, mpi4py communicator, None Communicator None

Return Value DistributedCSR.

Notes from_global() takes the owned rows from the whole matrix, so it is suitable for small problems and tests. It raises ValueError if the matrix is not square.

20.4 DistributedCSR.local_slice()

Description Returns the slice that takes the part owned by this rank from a global vector.

Synopsis

s = A.local_slice()          # slice(row_start, row_start + n_local)
x, info = parcel.solve(A, b_global[A.local_slice()])

20.5 parcel.solve()

Description Solves the linear system Ax=bAx = b and returns the solution and the convergence status (pcg, pbicgstab, pgmres, pcagmres).

Synopsis

x, info = parcel.solve(A, b, *, method="pcg", x0=None, tol=None, maxiter=None,
                       precond=None, precond_options=None,
                       restart=None, orthogonalization=None,      # pgmres only
                       s=None, t=None, qr=None, q_mode=None,      # pcagmres only
                       verbose=False)

Arguments The meanings of the settings are given in the sections of the “Common item” column.

Name Value Common item Default
A DistributedCSR Input matrix —
b Owned part of the right-hand side (length A.n_local) — —
method "pcg", "pbicgstab", "pgmres", "pcagmres" Solvers "pcg"
x0 Owned part of the initial guess; 0 if None — None
tol Finite positive number Convergence tolerance 1.0e-8
maxiter Integer, 1 or greater Maximum number of iterations 10000
precond None, "none", "point_jacobi", "block_jacobi", "jacobi" Preconditioner type No preconditioning
precond_options Dictionary: "iterations" (1 or greater), "blocks" (1 or greater), "scale_matrix", "scale_vector" (True, False, None) Jacobi iterations, blocks, scaling 1 iteration; blocks and scaling automatic
restart Integer, 1 or greater (pgmres only) Restart length 30
orthogonalization "cgs", "mgs" (pgmres only) Orthogonalization method "mgs"
s, t Integers, 1 or greater; give both (pcagmres only) Basis generation size 8, 4
qr "cgs", "mgs", "cholesky_qr", "cholesky_qr_moment" (pcagmres only) QR factorization method "mgs" ("cholesky_qr" with q_mode="implicit")
q_mode "auto", "explicit", "implicit" (pcagmres only) Q mode "auto"
verbose With True, rank 0 prints the progress of the iteration. With False, the standard output (file descriptor 1) is discarded while solving Standard output False

Requirements ValueError if the shapes of b and x0 are not (A.n_local,). A string value not among the candidates above or a number out of range raises ValueError. Giving restart, orthogonalization, s, t, qr or q_mode to a solver they do not apply to raises ValueError. Give both s and t. Unknown keys of precond_options raise ValueError. Invalid combinations (e.g., qr="cgs" with q_mode="implicit"; rules) are detected by the library, and all ranks raise the same ValueError.

Return Value (x, info). x is the owned part of the solution (float64 array), and info is a SolveInfo. Non-convergence does not raise an exception, so check info.converged.

MPI Collective operation (version with MPI).

See Also Convergence by Solver

Example

x, info = parcel.solve(A, b[A.local_slice()], method="pgmres", restart=60,
                       precond="jacobi", tol=1e-10)
if not info.converged:
    print(info.reason, info.iterations, info.true_residual)

20.6 parcel.eigs()

Description Solves the eigenvalue problem Av=λvAv = \lambda v (AK−1AK^{-1} when precond_spectrum=True) and returns the eigenvalues, the eigenvectors and the convergence status (power, inverse_power, ks_arnoldi).

Synopsis

values, vectors, info = parcel.eigs(A, *, method="ks_arnoldi", tol=None, maxiter=None,
        precond=None, precond_options=None, precond_spectrum=False,
        m=None, k_keep=None, nev=None, max_restart=None, sigma=None, v0=None,   # ks_arnoldi only
        orthogonalization=None,                                                 # ks_arnoldi only
        inner_method=None, inner_tol=None, inner_maxiter=None, inner_restart=None,
        inner_precond=None, inner_precond_options=None, verbose=False)

Arguments A, tol, maxiter, precond, precond_options and verbose are the same as in solve() (maxiter is the limit of the outer iterations of power / inverse_power; not used by ks_arnoldi).

Name Value Common item Default
method "power" (largest magnitude), "inverse_power" (smallest magnitude), "ks_arnoldi" (several from the largest-magnitude end) Solvers "ks_arnoldi"
precond_spectrum With True, computes the eigenvalues of AK−1AK^{-1} (KK is the preconditioner of precond) Spectrum of the preconditioned matrix False
m, k_keep, nev Maximum subspace dimension, number kept at a restart, number of eigenvalues sought (give all three; ks_arnoldi only) Size of the Krylov subspace 30, 10, 4
max_restart Integer, 1 or greater (ks_arnoldi only) Maximum number of restarts 200
orthogonalization "cgs" (CGS2) or "mgs" (MGS2); "cgs2" and "mgs2" are also accepted (ks_arnoldi only) Orthogonalization method Library default (CGS2; MGS2 depending on the build)
sigma Shift of shift-invert. If given, the eigenvalues near σ\sigma are sought (ks_arnoldi only) Shift-invert None (disabled)
v0 Owned part of the initial vector (length A.n_local; ks_arnoldi only) Initial vector None (built from the global row numbers)
inner_method "pgmres", "pcg" (used by inverse_power) Type of the inner linear solver "pgmres"
inner_tol Finite positive number Tolerance of the inner linear solver 1.0e-10
inner_maxiter Integer, 1 or greater Maximum iterations of the inner linear solver inverse_power 5000, ks_arnoldi 2000
inner_restart Integer, 1 or greater Restart length of the inner linear solver 30
inner_precond, inner_precond_options Preconditioner of the inner linear solver (same values as precond) and its "iterations" and "blocks" (the scaling is automatic; specifying it raises ValueError) Preconditioner of the inner linear solver "jacobi" (1 iteration); blocks automatic

Requirements m, k_keep, nev, max_restart, sigma, v0 and orthogonalization apply only to ks_arnoldi; giving them to other solvers raises ValueError. Values of orthogonalization other than the above also raise ValueError. Give all three of m, k_keep and nev; ValueError unless 1≤nev≤kkeep<m≤nglobal1 \leq nev \leq k_{keep} < m \leq n_{global}. The arguments of the inner linear solver are used by inverse_power and by ks_arnoldi with sigma. With precond_spectrum=True, pgmres is used regardless of inner_method. ValueError if the shape of v0 is not (A.n_local,).

Return Value (values, vectors, info). values is a 1-D complex array (1 element for power and inverse_power, k_keep elements for ks_arnoldi). vectors is an array of shape (A.n_local, count), whose column j is the owned part of the j-th eigenvector. The eigenvalues of ks_arnoldi are in descending order of absolute value (in order of closeness to σ\sigma for shift-invert), and the eigenvectors of a complex conjugate pair are stored as the real and imaginary parts in two consecutive columns (Output of Eigenvalues and Eigenvectors). info is an EigInfo.

MPI Collective operation (version with MPI).

See Also Notes on the Eigenvalue Solvers, Convergence by Solver

Example

# ks_arnoldi: 4 eigenvalues of largest magnitude; shift-invert: 2 eigenvalues closest to 0
vals, vecs, info = parcel.eigs(A, method="ks_arnoldi", m=40, k_keep=10, nev=4, tol=1e-10)
vals, vecs, info = parcel.eigs(A, method="ks_arnoldi", m=20, k_keep=6, nev=2, sigma=0.0,
                               tol=1e-10, inner_tol=1e-12)

20.7 parcel.SolveInfo / parcel.EigInfo

Description Results returned by solve() and eigs() (immutable data classes). The meanings are those of Results in Common Items, and the values are the same on all ranks.

Attribute Type Contents
converged bool True if converged
reason str Name of the convergence state: "converged" (CONVERGED_RTOL), "iterating" (ITERATING), "max_iterations" (DIVERGED_ITS), "nan_or_inf" (DIVERGED_NANORINF), "breakdown" (DIVERGED_BREAKDOWN)
reason_code int Value of the convergence state constant (1, 0, -1, -2, -3)
iterations int Iteration count
residual float Residual (the relative value used by the solver for the convergence check)
true_residual float True residual. NaN for the eigenvalue solvers
n_converged int EigInfo only. Number of converged eigenpairs
inner_failures int EigInfo only. Number of inner solver failures

20.8 parcel.Comm

Description MPI communicator passed to PARCEL.

Synopsis

c = parcel.Comm()             # MPI_COMM_WORLD (usable without mpi4py)
c = parcel.Comm(mpi4py_comm)  # mpi4py communicator
c.rank, c.size
v = c.allreduce(value, op="sum")      # "sum", "max", "min"

Arguments mpi4py_comm is an mpi4py communicator (MPI.Comm) or None. Passing an mpi4py communicator in the version without MPI raises TypeError. Passing something that is not an mpi4py communicator also raises TypeError.

Return Value rank and size are the number of this rank and the number of ranks (0 and 1 in the version without MPI). allreduce() returns the sum, maximum or minimum over all ranks (float) (collective operation; an invalid op raises ValueError).

Notes The comm argument of the matrix accepts either a parcel.Comm or an mpi4py communicator.

20.9 parcel.partition_rows()

Description Assigns n_global rows evenly to the ranks as contiguous row blocks.

Synopsis

row_start, n_local = parcel.partition_rows(n_global, comm=None)

Return Value (row_start, n_local) of this rank. The remainder is given one row each to the first ranks.

Requirements n_global is at least the number of ranks (otherwise ValueError).

20.10 parcel.build_info() / parcel.has_mpi() / parcel.device_name()

Description Return information about the native layer.

Function Return value
build_info() String with build information (widths of the integer types, precision, with or without MPI, ABI version; when installed with pip, also the target and the kernel optimization flags)
has_mpi() True if the native layer was built with MPI, False without MPI (single-process version)
device_name() Name of the device PARCEL uses on this rank (chosen by the default selector)

20.11 parcel.__version__ / parcel.library_version()

Description Return the version.

Name Value
__version__ Version string of the package ("1.2.0"; the same number as the library)
library_version() Version string of Include/parcel_version.hpp when the native layer was built. The same as __version__

20.12 Exceptions

Exception When raised
ValueError Invalid arguments or settings (outside the accepted values, invalid combinations), or the matrix check failed
OverflowError The number of rows etc. exceeds the range of the integer type of the native layer
TypeError The matrix is not a DistributedCSR, or the communicator has a wrong type
ImportError The native layer is not found, or its version (ABI) does not match
parcel.NotBuiltError The requested solver was excluded from the build (“Selecting the Solvers to Build” in the User Guide)
parcel.ParcelError Other failures (derived from RuntimeError; the base class of NotBuiltError; the attribute code holds the error code)

In the version without MPI, these exceptions can be caught in the calling process, and failures inside the library such as running out of device memory also raise parcel.ParcelError. In the version with MPI, errors detected by the library (invalid combinations of settings, the matrix check) raise the same exception on all ranks. Python-side checks such as array lengths and value ranges are made on each rank, so if the arguments differ between ranks and only some ranks raise, the remaining ranks wait forever in a collective operation. Other errors (such as running out of device memory) can occur on only some ranks, so a message is printed and all ranks are terminated with MPI_Abort.