ROCK  1.11.5
Relativistic Oscillator Calculation Kit
Changes

Rules

The Major.Minor.Patch versioning scheme has some differences from standard semantic versioning.

By increasing the version numbers,

  • Major: Architectural change or achievement of a significant milestone
  • Minor: Breaks backward compatibility
  • Patch: Fixes or features without breaking backward compatibility

Version 1

  • Future breaking changes
    • Remove RK4 refinement in cold cavity
    • Transpose nvmh_bcc to nvhm_bcc
    • Avoid in-place modification of matrix in API arguments
    • Cleanup cr_shoot_beamlet() masks
  • trunk
  • v1.11.5 (2026-11-11)
    • Fix a bug related to OpenMP actual thread number:
      • when OMP_THREAD_LIMIT < OMP_NUM_THREADS, or,
      • when OMP_NUM_THREADS is undefined while OMP_THREAD_LIMIT is defined to be less than the hardware thread number.
    • Support dim_m = 0 (however, keeping dim_z ≥ 2 due to base function, dim_b > 0 for dividing by dim_b when averaging)
  • v1.11.4 (2026-11-01)
    • Enable NoGIL in PROCK
    • Improve PROCK binding and fix minor bugs in the checking of dimensions
    • Add cr_make_mag_axis() for creating magnetic field from solenoids
    • Consider gamma in make_harm()
  • v1.11.3 (2026-10-25)
    • Fix an old mistake in the RK4 scan of cold resonance
  • v1.11.2 (2026-10-11)
    • Highlights of this release
      • Now with 8 harmonics (from -3 to 4) by default
      • Better energy convergence
      • Lower numerical error
      • Up to a 4× performance improvement, even with a doubled number of harmonics
    • Bugfix:
      • Fix mistake in guiding center calibration.
      • Fix energy conservation in mvn_src.
      • Use arithmetic mean for average gamma.
    • Refactor: Bessel J function
      • Remove the macro switch ROCK_ENABLE_FAST_BESL and always enable fast Bessel Jn(x).
    • Accuracy
      • Improve precision of the fast Bessel Jn(x), whose |n| <= 4 and |x| <= 16, avoid rational polynomial. (Now: FLT 2.4e-7 and DBL 7e-16)
      • Extend to -3 ... 4 harmonics, use this range by default
      • Add a test to ensure that the Kahan summation is not silently broken by compiler optimizations.
      • Use error-compensated y += a*b in many places
      • Reduce envelope noises in cr_step_field()
      • Add cr_make_stored_energy_diff() for better accuracy in calculation of energy difference (especially for fp32 build)
    • Performance
      • Batched evaluation of Bessel J order 0 to 4
      • Improve vectorization of many loops
    • Change of harmonic behavior: Harmonic number of each mode during cr_shoot_beamlet() will be only estimated once during cache creation, instead of re-calculating each time.
  • v1.11.1 (2026-07-16)
    • Improve scalability by removing atomic operations.
  • v1.11.0 (2026-07-04)
  • v1.10.0 (2026-06-06)
  • v1.9.4 (2026-04-28)
    • Validate vm_num, especially checking duplicated modes in the provided list.
    • Implement cr_make_stored_energy() for calculating hot Q.
  • v1.9.3 (2026-01-28)
    • Introduce ROCK_MASK_BLT_TREAT_BEAM_INIT_AS_RAW_IMPORT, when set in cr_shoot_beamlet(), the beam_init arguments are abused as a raw array of individual electrons and beam current is set to +1.0 Ampere (be careful with the sign convention of beam current).
    • Deprecate ROCK_MASK_BLT_DOPPLER, use ROCK_MASK_BLT_B_RF_PERP instead.
    • Degrade E_IB_SIGN to W_IB_SIGN.
    • Check more issues of input parameters in cr_shoot_beamlet().
    • Improve error messages.
    • Performance benchmark prints version number.
  • v1.9.2 2025-12-25 (Christmas)
    • Add more error check in make_chi_* functions.
    • Enhance reliability of cold cavity calculations.
    • Only find cold resonant modes with finite Q.
  • v1.9.1 2025-11-23
    • PROCK: Improve error message of parameters.
    • Simplify cold cavity RK4 refinement. The simplification may impact the precision of cold cavity solution.
    • Fix a bug in cr_find_cold_resonance() introduced from v1.8.0. Sanitizer could not find this bug, as all memories are valid.
    • Strength cold cavity functions by adding more asserts, which leads to an enhancement of the internal function make_omega_range().
  • v1.9.0 2025-11-14
    • Breaking change: Separate center radius and span of the bcc grid out of beam_init array, in order to support variable initial radius between iterations.
    • Fix a bug in passing span of bcc into cr_shoot_beamlet(), which was mistakenly treated as single-side spread instead of double-side span. The previous guiding centers were "squeezed", i.e. behaved more like classical codes without calibration of guiding center. After this bug fix, the error between Cartesian pusher and cyclotron pusher are further reduced. However, the overall impact on the typical simulation scenarios is tiny.
    • Fix a memory bug in cr_refine_z().
  • v1.8.0 2025-10-12
    • Implement mesh refinement (or re-arrangement).
    • Introduce opt_iz_min_fcut in cr_find_cold_resonance and cr_find_all_cold_resonances. Useful for excluding high-Q resonances long up-taper.
  • v1.7.7 2025-09-25
    • Fix an issue of invalid resonances with negative frequencies in the cr_find_all_cold_resonances(). (Negative frequencies were used to mark discarded data, however, they were not deleted as expected.)
    • Improve angle wrapping: faster and more precise. The improvement of precision can be observed e.g., in the electron position by using 32-bit floating point type on the duality (self-referred) test.
    • Improve accuracy of field solution as a compile-time option. Improving accuracy costs typically 8× time (at least 2×, max 128×), depending on the convergence.
  • v1.7.6 2025-09-16
  • v1.7.5 2025-09-06
    • Further improve performance by removing sincos()
    • Fix a bug introduced by v1.7.4 when minimum harmonic is not zero.
  • v1.7.4 2025-08-30
    • Perf: Improve performance of Lorentz force evaluation up to 80% in multimode simulations by transforming the code to assist the vectorizing or eliminate some elementary math functions.
    • Build: Remove CUDA device-link and device-LTO for performance.
    • Build: Overhaul the build system for preparing OpenCL-backend GPU build by chipStar.
  • v1.7.3 2025-08-16
    • CROCK: Clean the API macros without affecting the API functions. The CROCK library remains binary compatible.
    • Performance tuning
  • v1.7.2 2025-08-12
    • Remove a dummy memory barrier for synchronizing CPU caches.
      • On a Sandy-Bridge desktop CPU, adding the barrier improves performance by 2%.
      • On a modern heterogeneous CPU with P/E-cores, skipping the barrier improves performance by 2× on Linux, while nearly 20x on Windows.
  • v1.7.1 (Hotfix)
    • Fix a bug due to incorrect sorting of cold resonances
  • v1.7.0 2025-08-11
    • Use the concept span rather than spread, see the updated API documentation.
    • Previously only alpha was in Gaussian distribution, since this version both alpha and gamma are in Gaussian distribution.
    • Deprecate cr_search_cold_resonance(), use the new cr_find_cold_resonance() instead.
    • Feature: Add cr_find_all_cold_resonances()
    • Reverse the deprecation of calculating frequency shift in cr_step_field()
    • Cold: Spectrum calculation now based on FEM, like the new cr_find_cold_resonance().
    • PROCK: The minimum CPython version is now 3.11
    • PROCK: Fix compatibility issue starting from 3.1 version of Cython.
    • PROCK: PROCK is now built with stable API, however, Py_buffer requires stable API version 3.11.
    • PROCK: Remove PROCK version, since it is now tightly bound with CROCK.
    • Perf: Fix VW Diesel-Scandal on Windows
    • Perf: Enhance vectorization on some compilers
    • NUMA: Re-design cr_numa_bless() and the macro CR_NUMA_BLESS().
  • v1.6.3-build20250504 2025-05-04
    • build: Drop Python<=3.8 as it is End-of-Life
    • build: EL8 docker build switch from conda to uv (license issue)
    • build: Support numpy>=2.0
  • v1.6.3 2025-04-22
    • Fix cr_free() inconsistency among compilers on Windows
  • v1.6.2 2025-04-21 (Easter)
    • Avoid NaN in mvn_src at zero'th harmonic interaction introduced in v1.6.1
    • Fix a compatibility issue of Cython function return type
    • Free caches for sanitizer check
    • Add another test for second harmonic interaction
    • Improve the organization of installed header files
  • v1.6.1 2025-01-20
    • Add a high-order perturbation to the calculation of mvn_src.
    • Generate documentations of the data rows from the deployed rows.h.
  • v1.6.0 2024-12-17
    • Correct the equation for calculating the excitation (mvn_src). This correction should fix the magnitude of mvn_src in harmonic oscillation. However, since this formulation only considers the first low-order term in the expansion of eigenvector derivatives, the harmonics below the true harmonic number in the calculation of mvn_src may cause instability, therefore, they are omitted. If instability still appears, try to enable ROCK_MASK_BLT_SRC_MONOHARM.
    • Improve cold resonance calculation of cavities with up-taper. The position of cavity center can be optionally specified in cr_search_cold_resonance().
  • v1.5.0 2024-11-05
    • Support Python 3.13
    • Introduce option ROCK_MASK_BLT_SRC_MONOHARM, when enabled only a single harmonic contribution is taken into account. This is less accurate, but does not introduce other aliased frequencies. Note that the Lorentz force still includes all harmonics.
    • Rename ROCK_MASK_BLT_DEBUG to ROCK_MASK_BLT_MONOGC
    • Introduce cr_make_df() and deprecate the delta-frequency calculation in cr_step_field(). Instead of calculating frequency shift in a single cr_step_field() step, the average (but aliased) frequency shift, typically after every 100 steps, should be calculated. This avoids the drifting of carrier frequency by correlated noises.
    • Introduce cr_update_bc_simple() for a fake broadband Boundary Condition (BC): the matched frequency of a narrowband simple BC can be updated so often that the current transient field frequency of each mode is matched in the next step. If doing this with sufficient temporal resolution, the bandwidth of BC is effectively increased.
    • Cold resonance: Stay with the first axial mode when the cold cavity resonance spectrum is dense.
  • v1.4.0 2024-09-26
    • Support longitudinally corrugated hollow waveguides, however, only as impedance model.
    • Rename ROCK_MASK_BLT_GC_AZI_RF to ROCK_MASK_BLT_CALI_GC_AZI to be consistent with ROCK_MASK_BLT_CALI_CYC_PHASE.
    • Introduce option ROCK_MASK_BLT_CALI_GC_R.
    • Enhance tests.
  • v1.3.1 2024-09-13
  • v1.3.0 2024-09-11
    • Breaking change: Switch tri-diagonal matrix layout from row-based to diagonally based form.
    • Introduce ROCK_STRIDE wrapped to cr_stride_real() and cr_stride_cplx() for languages without C-macro capability.
    • Fix warning message of alignment.
    • Fix issue in corrugated coaxial mode solver, when two roots are very close to each other.
    • Let versions of CROCK and PROCK diverge.
  • v1.2.1 2024-08-30
  • v1.2.0 2024-08-23
    • Stricter memory alignments.
    • Disable the fast atan2() variant, since it causes wrong azimuthal bunching of guiding centers.
    • Add beamlet options:
      • MASK_BLT_CALI_CYC_PHASE: Consider calibration of cyclotron phase, reduce performance due to atan2().
      • MASK_BLT_GC_AZI_RF: Consider azimuthal motion (drift, oscillation etc.) of guiding center caused by RF field, reduce performance due to atan2().
      • MASK_BLT_ALL_FEATURES: All features except DEBUG. Slowest option.
  • v1.1.1 2024-08-16
    • Hotfix: Fix type of arguments in cr_numa_bless() in tests and PROCK. Depending on ABI, some systems may not be affected. (x64 Linux is fine, but x64 Windows ABI encounters problem)
  • v1.1.0 2024-08-15
    • Breaking change: Remove the deprecated mem_pool, use cr_cache instead.
    • Breaking change: The order vnb is changed to bvn. (e.g. in the array of electron position)
    • Significantly increase the OpenMP scalability
    • Reduce beamlet corrector step to 2.
    • Fix potential bug/mistake of data race
    • Warn if mesh discretization bigger than 4 times Larmor radius.
    • Deprecate GPU-offloading by OpenMP and OpenACC pragmas. With pragmas, the code is unclear covering all cases, while neither CPU nor GPU have the best performance.
  • v1.0.1 2024-08-02
    • Switch build system due to the difficulty in maintaining combinations of PIC+LTO+Offload+OffloadLib+OffloadLTO+StaticLib+__builtin_math portable among compilers.
  • v1.0.0 2024-07-19
    • Take into account multiple harmonics of the same mode
      • Deprecate make_harm()
      • Migrate vnm_bcc to nvmh_bcc
    • This is the last version using CMake.

Version 0

  • v0.5.4 2024-07-05
    • The latest release of 0 major version series
  • v0.5 2024-06-20
    • Add shift of carrier frequencies
  • v0.4 2024-06-18
    • Calculate Ohmic loads
  • v0.3 2024-06-12
    • Support corrugated coaxial cavities
  • v0.2 2024-06-10
    • Support coaxial modes
  • v0.1 2024-02-15
    • Initial release