API Reference

NucleiWoodSaxon3D{T,R,C,W,D1,D2,D3,D4,B,samp}

Representation of a deformed 3D Woods–Saxon nucleus suitable for sampling.

Fields

• N_nucleon::Int64 — number of nucleons per sample.
• α — surface diffuseness parameter.
• R — nuclear radius parameter.
• ρ₀ — central density normalization.
• w — quadratic modulation coefficient.
• beta2, beta3, beta4 — deformation parameters (spherical-harmonic multipoles).
• gamma — triaxiality angle used with beta2.
• burning_time — number of burn-in transitions for the internal MCMC sampler.
• sampler — internal Metropolis_Hastings sampler that proposes 3D locations according to the deformed density.
• d_min — minimum inter-nucleon separation (when zero no separation enforcement is performed).

Behavior

• Samples are drawn in 3D using the internal sampler and then a random 3×3 rotation is applied; the object returns transverse (x,y) coordinates (an (N_nucleon, 2) array) by projecting the rotated 3D positions.

Notes

• The type implements Sampleable{ArrayLikeVariate{2}, Continuous} and is intended for use with rand/Distributions.

IntegratedWoodSaxon{T,R,C,W,samp}

Representation of a two-dimensional, integrated Wood–Saxon nucleon distribution suitable for sampling.

Fields

• N_nucleon::Int64 — number of nucleons returned per draw (samples have shape (N_nucleon, 2)).
• α::T — surface diffuseness (or deformation parameter feeding into the radial dependence).
• R::R — characteristic nuclear radius used to set the spatial scale.
• ρ₀::C — central density normalization.
• w::W — optional quadratic deformation coefficient that modulates the radial profile.
• retol::Float64 — relative tolerance passed to the quadrature used when building the projected density.
• burning_time::Int64 — number of burn-in (warmup) iterations used by the internal Metropolis_Hastings sampler.
• sampler::samp — sampler object (typically Metropolis_Hastings) that draws correlated 2D positions from the projected density.
• rotated::Bool — when true, each sampled configuration is post-multiplied by a random RotMatrix{2} so the orientation is randomized.

Notes

• Implements Sampleable{ArrayLikeVariate{2}, Continuous} and is intended to be used with rand/Distributions to obtain (N_nucleon, 2) coordinate samples.
• The sampler targets the integrated (projected) density obtained by integrating the Woods–Saxon density along the longitudinal axis.

IntegratedWoodSaxonInterp{T,R,C,W,B,Inte,samp}

A sampleable object representing a two-dimensional integrated Wood–Saxon nucleon density.

Fields

• N_nucleon::Int64 — number of nucleons to draw per sample (returned sample has size (N_nucleon, 2)).
• α::T — diffuseness parameter (controls surface thickness).
• R::R — nuclear radius scale.
• ρ₀::C — central density normalization.
• w::W — surface diffuseness parameter.
• burning_time::B — number of burn-in (warmup) steps for the internal Metropolis–Hastings sampler.
• retol::Float64 — relative tolerance passed to the numerical quadrature used when building the interpolant.
• npoint::Int — number of grid points per axis used to compute the interpolant.
• interpolation::Inte — scaled B-spline interpolant (2D) approximating the integrated density used as a target for sampling.
• sampler::samp — sampler object (typically Metropolis_Hastings) used to produce correlated samples.
• rotated::Bool — if true, each sampled configuration is rotated by a random 2×2 rotation matrix before being returned.

Notes

• Implements Sampleable{ArrayLikeVariate{2}, Continuous} and provides size, dimension, and sampling via rand / Distributions._rand!.

TabulatedEvent(filename)

Load a set of precomputed light-ion configurations from an HDF5 file and construct a Sampleable over transverse nucleon positions.

File format

• The HDF5 file should contain a dataset named configs with shape (3, N_nucleon, N_configs), where the first axis indexes Cartesian coords (x,y,z), the second axis indexes nucleons, and the third axis indexes different configuration realizations.

Behavior

• Each sample selects a config index uniformly at random, applies a random 3D rotation (if rotated==true), projects to the transverse plane by taking the first two coordinates, and returns an (N_nucleon, 2) matrix of positions.

Example

julia> s = TabulatedEvent("configs.h5")
julia> pos = rand(s)  # pos has shape (N_nucleon, 2)

Uranium()

Return a Woods-Saxon uranium nucleus (A = 238) with default deformation parameters.

Lead()

Return a Woods-Saxon lead nucleus (A = 208) with default parameters.

Gold()

Return a Woods-Saxon gold nucleus (A = 197) with default parameters.

Copper()

Return a Woods-Saxon copper nucleus (A = 63) with default parameters.

Xenon()

Return a Woods-Saxon xenon nucleus (A = 129) with default parameters.

Oxygen()

Return a tabulated light-ion configuration for oxygen from the built-in artifact.

Neon()

Return a tabulated light-ion configuration for neon from the built-in artifact.

Participants{A,B,C,D,E,F,G,H,L}

Container describing a two‑nucleus collision setup and providing a Sampleable that generates Participant events.

Fields

• nucl1, nucl2 — nucleus samplers for the two colliding nuclei.
• sub_nucleon_width — Gaussian width (σ) used for the transverse matter distribution of sub‑nucleonic degrees of freedom.
• inpact_parameter_magitude — distribution for the impact parameter magnitude (radial distribution).
• inpact_parameter_angle — distribution for the impact parameter angle (azimuthal orientation).
• sigma_gg — per‑gluon (partonic) cross section used in computing binary collision probabilities.
• shape_parameter — Gamma distribution shape parameter used to sample per‑participant fluctuation weights.
• total_cross_section — inelastic nucleon‑nucleon cross section at the chosen energy (σ_NN).
• p — exponent used when combining thickness functions (p‑mean: p = 0 implies geometric mean).
• accumulation_preparation — precomputed data used to accelerate center‑of‑mass and accumulation calculations.

Notes

• Implements Sampleable{Univariate, Participant}, and rand(rng, participants) returns a sampled Participant event describing one collision configuration.

Participant

Container for a single sampled collision event.

Participant stores participant positions for both nuclei, per-participant weights, binary-collision count, sampling parameters, and derived quantities such as the impact parameter and total multiplicity. The object is callable: evt(x, y) returns the fluctuating thickness at (x, y).

threaded(elem)

Return a Threaded wrapper around elem to enable multithreaded sampling with rand.

Arguments

• elem — a Sampleable object (for example, an IntegratedWoodSaxon) which will be replicated into thread-local buffers.

Behavior

• Creates 2 * nthreads() thread-local copies by default via Threaded(elem, 2 * nthreads()).
• Each copy has an independent internal sampler state so concurrent calls to rand are thread-safe and do not share sampler state.
• When sampling with rand(rng, threaded(elem), n) the total workload is split among the internal buffers and executed in parallel, improving throughput on multi-core machines.

Examples

julia> s = IntegratedWoodSaxon(100, 0.5, 5.4, 0.16, 0.0)   # create a sampler for 100 nucleons
julia> ts = threaded(s)                                   # wrap for multithreaded sampling
julia> samples = rand(ts, 4)                              # produce 4 samples; returned matrix concatenates them

Notes

• This is a lightweight convenience function; it does not change the semantics or shape of the samples returned by elem.

Threaded(elem[, nbuffers])

Wrapper that stores thread-local copies of a sampleable object to enable multithreaded sampling with rand.

impactParameter(evt::Participant)

Return the impact parameter b for a sampled event.

multiplicity(evt::Participant)

Return the total multiplicity (entropy-like weight) for a sampled event.

n_coll(evt::Participant)

Return the number of binary nucleon-nucleon collisions in the event.

n_part(evt::Participant)

Return the number of participating nucleons in the event.

center_of_mass(con; Nr=64, Nth=64)

Compute center of mass using Gauss–Legendre quadrature in r and trapezoidal rule in θ. This converges faster than the uniform grid for smooth profiles.

Arguments

• con::Participant: The participant configuration.
• Nr: Number of Gauss–Legendre nodes (radial).
• Nth: Number of angular divisions (trapezoid).

Returns

• (mult, x_cm, y_cm): Multiplicity and first moments.

center_of_mass!(con, cache)

Non-allocating variant using pre-computed cache from prepare_accumulation(con, Nr, Nth).

Arguments

• con::Participant: configuration to integrate.
• cache: NamedTuple with (rvals, rweights, sinθ, cosθ).

Returns

• (mult, x_cm, y_cm): Multiplicity and first moments.

prepare_accumulation(con, Nr=64, Nth=64)

Pre-compute radial nodes/weights mapped to [0, Rmax] and sin/cos arrays for θ. Returns a NamedTuple (rvals, rweights, sinθ, cosθ) ready for use in _gl! functions.

Arguments

• con::Participant: participant to get R1, R2 from.
• Nr: Number of Gauss–Legendre nodes (radial).
• Nth: Number of angular divisions.

epsilon_n_psi_n(con, n; Nr=64, Nth=64)

Convenience wrapper that prepares a quadrature cache and calls epsilon_n_psi_n!(...).

Arguments

• con::Participant: Callable density/weight function con(x, y).
• n::Integer: Harmonic order.
• Nr, Nth: Optional quadrature resolution for radial and angular integrations (defaults: 64).

Returns

• (ε_n, ψ_n) from epsilon_n_psi_n!.

Example

ε2, ψ2 = epsilon_n_psi_n(participant, 2, Nr=128, Nth=128)

epsilon_n_psi_n!(con, cache, n)

Compute the nth-order eccentricity εn and event-plane angle ψn using a pre-computed quadrature cache.

Arguments

• con::Participant: Callable density/weight function con(x, y) that returns the local density at coordinates (x, y).
• cache: NamedTuple produced by prepare_accumulation, containing r_vals, r_weights, sinθ, cosθ, θ_weight, and θ_vals.
• n::Integer: Harmonic order (n ≥ 0).

Returns

• (ε_n, ψ_n): where
  • ε_n = sqrt(Q_x^2 + Q_y^2) / Q_0, with
    • Q_0 = Σ m(r, θ) * r^n,
    • Q_x = Σ cos(nθ) * m(r, θ) * r^n,
    • Q_y = Σ sin(nθ) * m(r, θ) * r^n,
    and m(r, θ) = con(x, y) * r_weight * θ_weight.
  • ψ_n = atan(Q_y, Q_x) (in radians).

Notes

• This is the non-allocating variant: it uses the supplied cache and avoids recomputing quadrature nodes/weights.
• The implementation uses sincos(n * θ) for angular factors; alternatively cos_sin_n(c, s, n) may be used when cos(θ) and sin(θ) are already available.

Example

cache = prepare_accumulation(participant, Nr=64, Nth=128)
ε, ψ = epsilon_n_psi_n!(participant, cache, 3)

generate_bg_twpt_fct(f, delta_factor, norm, Projectile1, Projectile2, w, k, p, sqrtS, bins, mList; ...)

High-level routine that generates a background profile and converts two-point correlators to the desired observable space.

Arguments

• f: Function applied to the normalized background values (e.g., equation-of-state transform).
• delta_factor: Function to convert entropy-space correlators to the target observable.
• norm: Normalization factor applied to profiles before averaging.
• Projectile1, Projectile2, w, k, p, sqrtS: Parameters used to construct Participants.
• bins, mList: Centrality bins and list of harmonics.
• Keyword arguments control event sampling and resolution: minBiasEvents, r_grid, NumPhiPoints, Threaded, Nfields.

Returns

• (bg, correlator): Background array and correlator tensor in the target observable space (after applying delta_factor).

Notes

• This wrapper samples events (threaded if requested), computes background (generate_bg) and entropy-space correlators (generate_tw_pt_fct_entropy) and then applies delta_factor pointwise to obtain correlator.

InverseFunction{N, F}(fun)

Wrapper for creating callable inverse functions. The returned object is callable: invf(x; u0=...) and numerically solves fun(u) = x for u.

Description

• InverseFunction(f) constructs a lightweight object holding f which can be used to compute the inverse of f numerically.
• The callable form invf(x; u0 = 0.1*one(x)) uses a Newton–Raphson solver (via NonlinearProblem and SimpleNewtonRaphson) to find u such that f(u) == x.

Arguments

• fun::F: A function of one variable mapping from domain to codomain.
• x: Target value for which the inverse is sought.
• u0: Optional initial guess for the root-finder (default 0.1 * one(x)).

Returns

• u: Numeric solution such that fun(u) ≈ x (returned from the solver's .u).

Notes

• The implementation uses a NonlinearProblem with a residual fun(u) - x and relies on SimpleNewtonRaphson for solving; users should ensure fun is reasonably well-behaved and provide suitable u0 for robust convergence.

Example

invf = InverseFunction(x -> 2x)
invf(1.0) # -> 0.5