Skip to content

Releases

PARCEL_SYCL v1.2.0

Choose a tag to compare

@parcel-jaea parcel-jaea released this 23 Oct 05:27

PARCEL_SYCL v1.2.0

v1.2

Changes from PARCEL_SYCL v1.0.

Added

Solvers

  • Eigenvalue solver parcel::krylov::ks_arnoldi (Arnoldi + Krylov-Schur restart).
    Computes the nev eigenpairs of largest absolute value, judging convergence by the Ritz residuals. The restart uses the real Schur form, so
    complex-conjugate pairs of eigenvalues of nonsymmetric matrices are also handled. With set_shift(σ) in shift-invert mode, the internal pgmres
    solves (A − σI) z = v and the eigenvalues near σ are computed. The orthogonalization is chosen with set_qr_algo() (the same constants as pgmres;
    in ks_arnoldi both are applied twice): QR_CGS is block classical Gram-Schmidt twice (CGS2, default) and QR_MGS is
    modified Gram-Schmidt twice (MGS2). Any other value gives std::invalid_argument. In C / Fortran it is ks_qr_algo of parcel_options,
    in Python orthogonalization of eigs() ("cgs" / "mgs"). On CPU configurations with a small local length per rank
    MGS2 can be faster, and on CPUs with a large local length and on GPUs CGS2 is faster. The accuracy of the eigenvalues is the same.
    The environment variable PARCEL_KS_ORTHO is not read (if it is set, rank 0 writes a one-line warning to standard error at the first solver()).
  • Eigenvalue solver parcel::krylov::power (power method). Computes the eigenvalue of largest absolute value.
    The initial vector is a combination of sin/cos built from the global row index (the same for any number of MPI processes).
  • Eigenvalue solver parcel::krylov::inverse_power (inverse power method). Computes the eigenvalue of smallest absolute value.
    The internal linear solver is pgmres (default) or pcg.
    power / inverse_power stop at the iteration where NaN / Inf appears and return DIVERGED_NANORINF
    (returning the last finite eigenvalue and the normalized vector).
  • Eigenvalues of the preconditioned matrix A K⁻¹: set_precon_spectrum(true), common to the eigenvalue solvers. The default (false) gives the eigenvalues of A.
  • Settings of the internal linear solver of the eigenvalue solvers: set_linsolve_algo / _tolerance / _max_iteration / _restart / _precon_algo / _blockjacobi / _jacobi / _scaling_matrix / _scaling_vector.
  • Choice of how pcagmres builds Q: set_explicit_q(CAGMRES_Q_AUTO / CAGMRES_Q_EXPLICIT / CAGMRES_Q_IMPLICIT).
    CAGMRES_Q_IMPLICIT is the Cholesky QR version that does not form Q explicitly (the algorithm of the v1.0 cholQR_pcagmres).
    If no QR is specified it uses QR_CHOLESKYQR; for a symmetric matrix, no preconditioning and even s, the moment method
    QR_CAGMRES_CHOLESKYQR can also be chosen.
  • Macro PARCEL_KS_ORTHO_DEFAULT, which selects at build time the default orthogonalization of ks_arnoldi (when set_qr_algo() is not called)
    (cgs2 / mgs; CGS2 if undefined). Added the variant ks_ortho (default cgs2) to the spack recipe, and set it to mgs in the PS-A definition (spack/stack/envs/psa) and in
    the tests ps_a / ps_aspack (MGS2 is the default on PS-A). A build that does not define the macro has an unchanged preprocessed source.

APIs

  • Convergence status API (all solvers): get_converged_reason() (CONVERGED_RTOL / DIVERGED_ITS /
    DIVERGED_NANORINF / DIVERGED_BREAKDOWN), is_converged(), get_iterations(), get_residual(),
    get_true_residual(). The eigenvalue solvers have get_linsolve_failures(), and ks_arnoldi has get_ks_nconv().
    Rank 0 writes one line converged_reason = ... , its = ... at the end of solver().
  • API for calling all 7 solvers from C / Fortran (capi/parcel_sycl_c.h, capi/parcel_sycl_mod.f90,
    capi/wrapper_parcel_sycl.cpp): parcel_solve_linear / parcel_solve_eigen (_f for Fortran),
    the settings structure parcel_options (parcel_options_init() reads the defaults from the library), the result structure
    parcel_result, uneven row partitioning, and error codes (PARCEL_ERR_*). The v1.0 run_parcel_sycl_c / _f are
    kept for compatibility.
  • Python package parcel (python/): calls all 7 solvers from a native layer independent of the C / Fortran APIs (python/src/parcel_py.cpp)
    (parcel.solve / parcel.eigs, double precision, without / with MPI). Install with pip (scikit-build-core) or with spack's
    py-parcel-sycl. See python/README.md.
  • Version information: Include/parcel_version.hpp (read by parcel_sycl.hpp) with PARCEL_VERSION_MAJOR / _MINOR / _PATCH,
    PARCEL_VERSION_STRING ("1.2.0"), PARCEL_VERSION_NUMBER, PARCEL_VERSION_GE(a, b, c), and parcel::version_string() /
    parcel::get_version(). parcel_get_version() / parcel_version_string() in the C / Fortran APIs, and parcel.library_version() in Python.
    The version of the Python package changed from 0.1.0 to 1.2.0, the same as the main package. The files that copy the version (the Python package, the spack recipes,
    CITATION.cff) are checked against each other by tests/check_version.py, and the regression tests compare the version that was run with the value the generator takes from the header
    (the [VERSION] line of the verification sample, and the version item of the C / Fortran / Python tests).

Input checks and diagnostics

  • Input checks:
    • set_crsMat() checks the row-block partitioning (all ranks together cover [0, n) with no gaps or overlaps) and the local CRS (the ranges of the row pointers and column indices),
      and if they are broken all ranks throw the same std::invalid_argument (can be disabled with -DPARCEL_NO_CRS_CHECK=1).
    • Out-of-range values of arguments to the setting functions and to solver() give std::invalid_argument.
    • If the SYCL queue is not in-order, std::invalid_argument (can be disabled with -DPARCEL_REQUIRE_IN_ORDER=0).
    • If a device memory allocation fails, util_sycl::device_bad_alloc (derived from std::bad_alloc) is thrown.
    • A build with -ffast-math is stopped by #error (because it breaks double-double and NaN detection;
      allowed with -DPARCEL_ALLOW_FAST_MATH).
  • Runtime environment variable PARCEL_TIMER_SYNC=1: synchronizes the device before and after the timing of inner products and of axpy with coefficients passed by value
    (by default there is no synchronization, and the inner-product time includes the time of the preceding kernel (such as the axpy of MGS). Use it to get an accurate breakdown of the time).
  • Runtime environment variable PARCEL_MEM_REPORT: when set, PARCEL counts the current amount and the peak of the device memory it allocated with USM
    (readable with util_sycl::device_mem_peak_bytes(); the verification sample prints it as PARCEL device peak after the solver).

Build options

  • Build without MPI -DPARCEL_MPI=0: does not read mpi.h, and builds a single-process version without the MPI compiler wrapper.
    Create it with parcel::comm comm(&q); set_crsMat(&comm, nstart, nend, ...) and the others are used in the same form as with MPI.
    The C / Fortran APIs use the same functions, and the communicator argument is not used. The results are bitwise identical to a single process with MPI.
    For usage see "Build without MPI" in the Installation chapter of the manual (doc/en/user/installation.html#install-nompi).
  • Switches to limit which solvers are built: PARCEL_ENABLE_ALL_SOLVERS / PARCEL_ENABLE_<solver> (all by default).
  • PARCEL_FP_CONTRACT_OFF: enables #pragma clang fp contract(off) (effective only together with
    -ffp-contract=fast-honor-pragmas; to get identical results across rebuilds, -ffp-contract=off is recommended).

Installation and examples

  • spack recipes and a mechanism for installing from scratch (spack/): parcel-sycl (headers, C / Fortran APIs) and py-parcel-sycl;
    spack/stack/install_stack.sh, which installs everything from fetching spack through LLVM, AdaptiveCpp, OpenBLAS, Python and PARCEL, and the checker
    check_stack.sh; definitions of 7 environments (spack/stack/envs/; Wisteria-Odyssey uses +fj with the Fujitsu compiler, MPI and LAPACK). A template spack/stack/envs/generic/ to be adapted for other Linux machines (checked on Ubuntu 24.04 and Rocky Linux 9 (both on WSL2)). On V100 (cuda_arch=70), -Xcuda-ptxas -maxrregcount=255 is added automatically.
    See spack/README.md.
  • Examples examples/quick_start.cpp (minimal pcg) and examples/example_pcg_ks.cpp (pcg + ks_arnoldi).
  • C / Fortran / Python versions of the quick start (examples/quick_start_c.c, quick_start_f.f90, quick_start.py): solve the same problem as quick_start.cpp
    (the 1D Laplacian with n = 1000 by pcg without preconditioning) with the C / Fortran APIs and the Python package. The same source works without and with MPI.
  • Checking the build: the 4 quick starts (C++, C, Fortran, Python) compute the maximum relative error against the exact solution x[i] = (i + 1)(n − i) / 2
    over the rows owned by each rank, gather it, and judge it with the threshold 1e-6 (check: max relative error = ... (limit 1.0e-06) PASS; on failure the exit code is 1).
    examples/run_quick_checks.sh (new) builds and runs them, with MPI also runs the C++ one with 2 processes,
    and prints PASS n / FAIL m on one line (without MPI PARCEL_MPI=0, launch commands MPIEXEC, MPIEXEC_NP_FLAG and so on; Python is SKI...
Read more

PARCEL_SYCL v1.0.0

Choose a tag to compare

@parcel-jaea parcel-jaea released this 22 Oct 09:11

PARCEL_SYCL v1.0.0, the first SYCL version (released on the distribution site in June 2025). Past version. For new work use the latest release.

  • Source tarball: PARCEL_SYCL_v1.0.tar.gz (same file name and top directory as formerly on the distribution site)
  • SHA-256: 410784a715d331c2c0b387be88122333363d2fe6091101979e7cce204c3c5ef2 (also in PARCEL_SYCL_v1.0.tar.gz.sha256; check with sha256sum -c PARCEL_SYCL_v1.0.tar.gz.sha256)
  • Manual: manual/PARCEL_manual.html (Japanese) and manual/PARCEL_manual_eng.html (English) in the tarball, also in the tag: Japanese / English
  • License: LGPL-3.0
  • Contact: GitHub Issues, https://github.com/parcel-jaea/PARCEL-release/issues

Differences from the tarball formerly on the distribution site: macOS metadata files (._*, 110 files) and extended attributes are removed, a commented-out line with a personal path in Include/parcel_type.hpp is removed, the manual (HTML, formerly distributed separately) is added in manual/, the license texts COPYING / COPYING.LESSER are added, file owners are not recorded and the timestamps are set to 2025-06-12.

The PARCEL versions before SYCL (1.0 – 1.2, Fortran / CUDA) are in https://github.com/parcel-jaea/PARCEL-legacy.