15 Versions and Compatibility
This chapter summarizes the changes from the public release v1.0 to v1.2 that affect user programs. Deprecated functions are noted at each function in the API Reference. For the detailed history of changes, see CHANGELOG.md in the repository.
15.1 Compatibility Policy
- When the name, arguments, or default behavior of the public API (the classes, functions, macros, and C/Fortran functions described in the API Reference and “Usage” of this manual) is changed, the change is recorded in this chapter.
- A renamed function keeps its old name as an alias at least until the next version, and the old name is marked as deprecated in the API Reference.
- The format of the standard output, such as the output of execution times and progress messages, is not part of the API. To obtain results from a program, use the functions that retrieve the convergence status (“Common Member Functions” in the API Reference).
15.2 Checking the Version
The version is defined in one place, Include/parcel_version.hpp (this version is 1.2.0, released on 2026-10-23). Each language obtains it as follows (C++, C, Fortran and Python in the API Reference).
| Language | How to obtain the version |
|---|---|
| C++ | Macros PARCEL_VERSION_MAJOR / PARCEL_VERSION_MINOR / PARCEL_VERSION_PATCH, PARCEL_VERSION_STRING, PARCEL_VERSION_NUMBER, PARCEL_VERSION_GE(a, b, c). Functions parcel::version_string() and parcel::get_version() |
| C | parcel_get_version(), parcel_version_string() (the values when the wrapper was built) |
| Fortran | parcel_get_version(), parcel_version_string() |
| Python | parcel.__version__ (version of the package) and parcel.library_version() (the value when the native layer was built). Both have the same value |
The Python package has the same version number as the library. The regression tests check that the version of the program run agrees with the version the generator reads from the header.
15.3 Citation and Support
Citation information is in CITATION.cff (Citation File Format 1.2.0) of the distribution package. When citing PARCEL, cite reference [3] (Idomura et al., ScalA 17, 2017). Questions and bug reports are accepted on GitHub Issues (https://github.com/parcel-jaea/PARCEL-release/issues). How to get support and what to include in a report (version, how it was installed and the build commands, the computer, versions of the SYCL implementation and MPI, steps to reproduce) are in SUPPORT.md. The public repository is https://github.com/parcel-jaea/PARCEL-release (the distribution tarball is on its Release).
15.4 Verifying the Distribution
The distribution tarball parcel_sycl-1.2.0.tar.gz is placed on the GitHub Release (https://github.com/parcel-jaea/PARCEL-release/releases, tag v1.2.0) with a sha256 file parcel_sycl-1.2.0.tar.gz.sha256. Check a received tarball with sha256sum -c parcel_sycl-1.2.0.tar.gz.sha256 (shasum -a 256 -c on macOS). The tarball is created with tools/make_tarball.py, and the same contents always give the same tarball (the same sha256). Whether the sha256 written in the spack recipes agrees with the tarball of the current package is checked with python3 tools/make_tarball.py --check. Because the recipes are also in the tarball, the recipes inside the tarball are stored without the sha256.
Past versions are also on GitHub Releases: SYCL version v1.0 on the Release of the same repository (tag v1.0.0), and PARCEL 1.0–1.2 before the SYCL version (Fortran, CUDA) on the Releases of https://github.com/parcel-jaea/PARCEL-legacy.
15.5 Changes from v1.0 to v1.2
15.5.1 Changed Behavior
Features that existed in v1.0 and whose behavior changed in v1.2. v1.0 has no functions that return the convergence status, so the v1.0 column describes how the iteration ended.
| Item | v1.0 | v1.2 |
|---|---|---|
Class template arguments of pbicgstab |
Five arguments including an unused leading Tdata. Passing the same four arguments as for the other solvers shifted them by one, so SpMV was computed in the precision of the preconditioner and the inner products always in double |
<Tspmv, Tprecon, Taxpy, Tdot>, the same as the other solvers |
| Number of blocks of the block Jacobi preconditioner | Default 1 | Determined automatically from the parallelism of the device unless set_blockjacobi() is called |
| Matrix and vector scaling of the preconditioner | Disabled by default | Determined automatically from the type and precision of the preconditioner unless set_scaling_matrix() / set_scaling_vector() is called (always enabled for block Jacobi; enabled for Jacobi only in half precision) |
| SYCL queue | The default (out-of-order) queue was also accepted (the bundled sample and wrapper used the default queue with AdaptiveCpp) | set_crsMat() and solver() of all solvers throw std::invalid_argument unless the queue is in-order |
| Arguments of the setter functions | Out-of-range values were accepted with undefined results (e.g. set_precon_algo(3) silently meant no preconditioning, set_tolerance(0) iterated up to the maximum) |
Out-of-range values throw std::invalid_argument (“Handling of Settings and Exceptions” in the API Reference) |
| Linear solvers with | The relative residual became NaN, and the solver iterated up to the maximum number of iterations | Returns without iterating, with CONVERGED_RTOL (0 iterations) |
| Linear solvers with a non-finite residual | Iterated up to the maximum number of iterations | Stops immediately with DIVERGED_NANORINF |
Breakdown of pbicgstab |
Not detected; iterated up to the maximum number of iterations with NaN / Inf | Detects zeros of , , and others, and returns DIVERGED_BREAKDOWN; is checked as a lucky breakdown |
Lucky breakdown of pgmres / pcagmres |
NaN from division by zero, or a solution update containing garbage | The solution is updated with the valid columns only and checked at the next restart; DIVERGED_BREAKDOWN if no update is possible |
-ffast-math / -ffinite-math-only |
Could be built | The build is stopped with #error |
| Error-free transformation of double-double products (TwoProd) | Dekker splitting. With CUDA, products and sums are fused into FMA, so dd products may degrade to double precision | Uses fma. dd results may change in the last digit |
FP16 inner products of pbicgstab |
Because of the shifted template arguments, the inner products were always computed in double (even in FP16 configurations) | The inner products are computed in FP16, and the solver may end with DIVERGED_BREAKDOWN near the attainable residual of the precision |
Default of set_tolerance() (all solvers) |
1.0e-4 | 1.0e-8 |
Default of set_max_iteration() |
100 | 10000 |
Default of set_restart() of pgmres |
4 | 30 (pgmres holds work vectors, so the default memory usage grows) |
Default of set_restart(s, t) of pcagmres |
, | , |
Default of set_qr_algo() of pcagmres |
QR_CGS |
QR_MGS (QR_CHOLESKYQR with CAGMRES_Q_IMPLICIT if not specified). The default of cagmres_qr_algo in C / Fortran is also PARCEL_QR_MGS |
pgmres / pcagmres with an iteration limit that is not a multiple of the restart length (, ) |
The number of cycles was rounded down and the remaining iterations were not performed (no iteration if the limit was smaller than the cycle) | The last restart is shortened, and the solver iterates exactly up to the limit; the iteration count is the limit if it is reached |
pcg / pbicgstab with a relative initial residual below the tolerance |
At least one iteration (if is the exact solution and the initial residual is 0, division by zero gives NaN) | Returns CONVERGED_RTOL without iterating (0 iterations, x unchanged) |
Default of PARCEL_INT (integers such as row and column indices) |
int32_t (int64_t with -DPARCEL_INT) |
The global index PARCEL_INT is int64_t. The indices within a rank (the column indices and row pointers of the CRS on the device, etc.) are held in the new PARCEL_LINT, int32_t by default, so the device memory and the SpMV traffic are the same as in v1.0. The arrays passed to set_crsMat() become PARCEL_INT (8 bytes) (“Integer Type” in “Basic Structure”). -DPARCEL_INT is accepted for compatibility |
Input of set_crsMat() |
Not checked (gaps or overlaps of the partition or errors in rowptr gave wrong results or out-of-range accesses) |
Checks the partition, the numbers of local rows, rowptr and the column indices, and throws std::invalid_argument on all ranks if they are inconsistent (“Setting the Matrix” in “Usage”) |
| Failure of device memory allocation | Not checked (the program crashed with a segmentation fault or similar) | Throws util_sycl::device_bad_alloc (derived from std::bad_alloc) |
Lifetime of the Jacobi preconditioner (PRECON_JACOBI) and the matrix |
The preconditioner held copies of the row pointers and column indices of | They are shared with without copying, and by default the values of are also read at every application. No effect as long as is not destroyed or modified while solver() is running. If a preconditioner matrix parcel::precon_matrix is constructed and used directly, do not destroy or modify before finishing with it |
| Values of of the Jacobi preconditioner | Stored | Not stored; computed from the values of at every application (less memory by one element of the preconditioner matrix precision per nonzero of ; slower preconditioner on GPUs; identical results with -ffp-contract=off) |
Solution update of pcg |
4 search directions accumulated and added every 4 iterations | Updated at every iteration with a single search direction (memory of 3 vectors less, slightly slower; results differ in the last digits; same number of iterations) |
Integer arguments of the legacy C / Fortran API run_parcel_sycl_c() / run_parcel_sycl_f() |
32-bit int (C) / integer(kind=4) (Fortran) |
64-bit parcel_int (C) / integer(c_int64_t) (Fortran). The arrays of the caller must also be 64-bit |
15.5.2 Added Features
- Eigenvalue solvers
parcel::krylov::power,parcel::krylov::inverse_powerandparcel::krylov::ks_arnoldi(v1.0 has linear solvers only) - Settings common to the eigenvalue solvers (
set_precon_spectrum,set_linsolve_*) - Output of the internal variables and a shift for right-preconditioned
pgmres(set_precon_space_output,set_shift), and a fourth argument ofsolver()for passing an externally constructed preconditioner matrix - Retrieval of the convergence status (
get_converged_reason(),get_iterations(),get_residual(), and others) - Selection of how
pcagmresforms the orthonormal basis (set_explicit_q()/get_explicit_q(), constantsparcel::krylov::CAGMRES_Q_AUTO/CAGMRES_Q_EXPLICIT/CAGMRES_Q_IMPLICIT; Linear Solvers chapter). WithCAGMRES_Q_IMPLICIT,parcel::qr::QR_CAGMRES_CHOLESKYQR(the moment method) can also be used.Todd_basisandTeven_basis(defaultTbasis) are added at the end of the template arguments ofsolver(). From C / Fortran,cagmres_q_modeofparcel_optionsandPARCEL_CAGMRES_Q_* - Default
parcel_doublefor the precision template arguments (parcel::matrix<>,parcel::vector<>, and the data precisions ofsolver()of each solver that cannot be deduced from the arguments). One can writeparcel::krylov::pcg<> s; s.solver(A, x, b); parcel::matrix::n_local()(number of local rows)- MPI support of
set_crsMat(comm, nstart, nend, n, nnz, rowptr, crsCol, hi, lo), which takes the high and low parts of double-double in separate arrays (in v1.0 it did not register the communicator and could not be used withPARCEL_MPI=1) - Macros
PARCEL_ENABLE_ALL_SOLVERSandPARCEL_ENABLE_<solver>for selecting the solvers to build (“Macros” in the Installation chapter) - Macros for build-time checks and numerical operations
PARCEL_REQUIRE_IN_ORDER,PARCEL_NO_CRS_CHECK,PARCEL_ALLOW_FAST_MATH,PARCEL_DD_NO_FMA - Macros
PARCEL_JACOBI_ONTHEFLYandPARCEL_PCG_NO_XHISTand the environment variablePARCEL_PSTEPfor choosing between memory and speed (“Optimization” in the Installation chapter) - The type
PARCEL_LINTof the indices within a rank (32-bit by default), the integer-type macrosPARCEL_INT32andPARCEL_LOCAL_INT64, andPARCEL_INT_BITSandPARCEL_LINT_BITS, which give the selected widths (“Integer Type” in the Installation chapter) - Macro
PARCEL_KS_ORTHO_DEFAULTand spack variantks_orthofor selecting the default orthogonalization ofks_arnoldiat build time (“Default Orthogonalization of ks_arnoldi” in the Installation chapter) set_qr_algo()/get_qr_algo()ofks_arnoldifor selecting its orthogonalization (the same constants aspgmres;ks_qr_algoofparcel_optionsin C and Fortran,orthogonalizationofeigs()in Python)- Run-time environment variables
PARCEL_TIMER_SYNC(synchronization for timing) andPARCEL_MEM_REPORT(recording of the peak device memory allocated by PARCEL;util_sycl::device_mem_peak_bytes()) (table of environment variables in Usage) - Work-group synchronization
util_sycl::group_barrier()(for its use, see “Compiling and Running” of C++ in Usage) - Build without MPI (
-DPARCEL_MPI=0;PARCEL_MPIwas fixed to 1 in v1.0; see “Build without MPI”), with the constructorcomm(sycl::queue*)ofparcel::commfor it - The verification sample
tests/verify/parcel_krylov_sample_verify.cpp(compares with reference solutions; the solver, preconditioner and problem are selected at run time) and the generators of the regression and performance tests (tests/) - The Python package
parcel(python/; all solvers can be called; double precision only; Python in “Usage”) - spack recipes
parcel-sycl/py-parcel-sycland the script that installs everything from fetching spack to PARCEL (spack/; “Installing with spack” in “Installation”) - Tests of the C, Fortran and Python APIs in the regression tests, a mechanism to select with or without MPI and the languages, and running on machines without a scheduler (
tests/regression/) - API for calling all solvers from C / Fortran (
capi/parcel_sycl_c.h,capi/parcel_sycl_mod.f90). The integer typesparcel_int(C) /parcel_int_kind(Fortran) are 64-bit. The C / Fortran API of v1.0 is only the legacyrun_parcel_sycl_c()/run_parcel_sycl_f(), which solve with pcg
15.5.3 Removed Features
| Item | Replacement |
|---|---|
parcel: (in v1.0, instantiating its solver() did not compile, so it could not be used) |
parcel::krylov::pcagmres with set_explicit_q(parcel: (the QR factorization is QR_CHOLESKYQR unless specified) |
The sample parcel_krylov_sample.cpp and its settings parcel_default.hpp (top-level directory) |
The verification sample tests/ (the solver is selected at run time with PARCEL_SOLVER) and the samples in examples/ |
The file layout also changed: the C / Fortran API (wrapper_parcel_sycl.cpp, parcel_sycl_c.h, parcel_sycl_mod.f90) is in capi/, and the samples (sample_c.c, sample_f.f90, problem.f90) are in examples/ (“Package Layout”).