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.
- The public names are
DistributedCSR,solve,eigs,SolveInfo,EigInfo,Comm,partition_rows,build_info,has_mpi,device_name,ParcelErrorandNotBuiltError. - One call creates the SYCL queue, registers the matrix and solves. Only double precision is available (Precision) for both data and computation, and the input/output arrays are float64.
- Settings arguments given as
None(the default) take the library defaults (common settings). The “Default” column of the argument tables below gives those values. - Errors are reported with Python exceptions (Exceptions). A solve does not raise an exception when it does not converge, so check
info.convergedin the result. - In the version whose native layer is built with MPI, all ranks make the same calls with the same arguments (collective operations). MPI is initialized at the first call (if mpi4py or another module has already initialized it, that is used, and the package calls
MPI_Finalizeat exit only when it initialized MPI itself). In the version without MPI, a single process holds everything. - The native layer is loaded from the path in the environment variable
PARCEL_PY_LIBif set, otherwise fromlibparcel_py.soin the package. If it is not found or its version (ABI) does not match the package,ImportErroris raised. To suppress warnings of AdaptiveCpp,ACPP_DEBUG_LEVELis set to 0 unless already set.
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 , | 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 |
| 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 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 ( 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 ( 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 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 . 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 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.