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

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

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 ∥b∥=0\|b\| = 0 The relative residual became NaN, and the solver iterated up to the maximum number of iterations Returns x=0x = 0 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 ⟨r*,q⟩\langle r^{\ast},q \rangle, ω\omega, ρ\rho and others, and returns DIVERGED_BREAKDOWN; v=0v = 0 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 m+1m+1 work vectors, so the default memory usage grows)
Default of set_restart(s, t) of pcagmres s=1s = 1, t=1t = 1 s=8s = 8, t=4t = 4
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 (mm, stst) 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 x(0)x^{(0)} 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 AA The preconditioner held copies of the row pointers and column indices of AA They are shared with AA without copying, and by default the values of AA are also read at every application. No effect as long as AA 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 AA before finishing with it
Values of B=DA−1RB = D_A^{-1}R of the Jacobi preconditioner Stored Not stored; computed from the values of AA at every application (less memory by one element of the preconditioner matrix precision per nonzero of AA; slower preconditioner on GPUs; identical results with -ffp-contract=off)
Solution update xx 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

15.5.3 Removed Features

Item Replacement
parcel::krylov::cholQR_pcagmres (in v1.0, instantiating its solver() did not compile, so it could not be used) parcel::krylov::pcagmres with set_explicit_q(parcel::krylov::CAGMRES_Q_IMPLICIT) (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/verify/parcel_krylov_sample_verify.cpp (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”).