Prescribed species profiles
Species.prescribed_profiles holds XGC input-defined radial functions for
each species. Their evaluate_raw(psi_n) method evaluates the input shape;
Species.evaluate_input_profile(name, psi_n) is a convenience wrapper.
Species.initial_profiles remains the earlier file-only API, including its
existing interpolate_profile behavior. It is distinct from evolving
diagnostics and Diffusion Optimizer output.
Heat and torque inputs in src_param define deposition weights, not
physical source-rate profiles. Species.deposition_shapes holds one
DepositionShape per active region. A shape is separate from the
whole-torus src_heat_power* (W), src_torque* (N m), XGC’s volume
normalization, and source timing. Do not label its output W, N m, W/m³, or
N/m². The special divertor/SOL mode multiplies by a Z distance in metres, so
that mode’s unnormalized weight has units of metres.
Profile families
All families use normalized poloidal flux psi_n = psi / psi_norm. For the
2D equilibrium, psi_norm is the first X-point flux. Values below are raw
input-function units, before any XGC flow conversion, edge/private decay,
region mask, or source normalization. Arrays in eq_param and src_param
are indexed by zero-based species index in Python; XGC’s first entry is the
electron in the common electron/main-ion setup.
Inputs / Python key |
Scope |
Values / units |
Shape IDs |
Parameters and defaults |
|---|---|---|---|---|
|
per species |
density, m⁻³ |
-1, 0, 1, 2, 5 |
|
|
per species |
temperature, eV |
same |
|
|
per species |
raw flow, m/s for type 0; rad/s for types 1/2 |
same |
coefficients default 0; |
|
per species |
m²/s |
same |
coefficients default 0 |
|
per species |
m²/s |
same |
coefficients default 0 |
|
per species |
m²/s |
same |
coefficients default 0 |
|
per species |
m/s |
same |
coefficients default 0 |
|
per species |
eV |
same |
inherit |
|
per species |
m/s or rad/s according to their flow type |
same |
inherit |
|
per species |
m⁻³ s⁻¹ |
same |
|
|
run-wide, when |
dimensionless |
same |
|
|
per species and region |
unnormalized weight, dimensionless or m |
1 trapezoid, 2 Gaussian |
|
XGC’s shared Eq::Profile accepts shape 0 (constant v1), 1
(tanh transition with x1 center and x2 width), 2 (linear from
(x1,v1) to (x1+x2,v2)), 5 (pedestal/core expression), and -1
(file). Shape IDs 3, 4, and 6 are not accepted by the current
shape_from_int. Files use XGC’s count/psi_n value/-1 format;
the reference implementation fits a not-a-knot cubic spline, samples it at
1000 equally spaced flux points, then linearly interpolates those samples.
The legacy interpolate_profile method remains a direct numpy.interp
of file points, preserving earlier callers.
When sml_input_file_format='adios', file-shaped equilibrium density,
temperature, flow, f-grid, and marker profiles come from
sml_input_package_file groups under /profiles. They are read through
the catalog when that BP file is registered as a product. F-grid and marker
file profiles without an explicit override inherit their base profile, as in
XGC. Particle-source, transport, and effective-charge file profiles still
use text files in this mode. A missing package product or group is reported
instead of substituting a text profile. The older initial_profiles
dictionary describes text file inputs only. The current directory catalog
discovers BP products only at the run root. A package in a nested or external
sml_input_file_dir must already be registered under its relative package
path; otherwise evaluation reports that the package is unavailable.
Spatial and runtime limits
XGC’s Eq::Profile::value uses R/Z geometry to classify core/edge versus
private-flux locations. PrescribedProfile.evaluate_with_region reproduces
its configured exponential decay when the caller supplies core_edge,
private_lower, or private_upper; the upper region also needs its
X-point flux. Flux alone cannot determine a region. Species reads the
sml_outpsi and eq_*_decay_* defaults for its convenience wrapper.
For a lower private-flux query, supply the actual lower X-point flux divided
by the run’s psi normalization as xpoint_psi_n. This ratio need not equal
one for a 3D equilibrium.
For more than two species, XGC may construct one species’ density from the
other species to enforce quasineutrality. The responder’s eq_dens shape is
not the applied density; Species.evaluate_input_profile('density', ...)
reports this instead of silently returning it. XGC also derives the applied
electron particle-source increment from ion charge balance and applies
particle sources only in its selected core region. Those operations require
the evolving simulation state.
DepositionShape.evaluate_weight evaluates the radial trapezoid or
Gaussian, circular region, or Z-weighted shape defined by the inputs. XGC
additionally applies region and wall masks, then normalizes heating and torque
against the active deposition volume. Thus the shape does not reconstruct a
volumetric heat or torque source from the input alone.
References and checks
The formulas and defaults were read from the paired XGC-Devel sources:
XGC_core/cpp/plasma/profile.hpp, profile_setup.F90,
initialize_equil_profiles.cpp, sources/diffusion_profiles.cpp,
sources/particle_source.cpp, sources/heat_torque.cpp and
heat_torque.hpp, and sources/radiation.cpp. Direct-reference numeric
cases for shapes 0, 1, 2, 5, file interpolation, edge/private decay, and
heat/torque weights are in tests/test_prescribed_profiles.py. The local
xgc1_sample supplies two species with 88-point density, temperature, and
flow files and active heat/torque region inputs. A full coupled XGC run is
still needed to compare geometry masks and normalized physical source rates.
Example:
species = simulation.species[1]
psi_n = [0.4, 0.8, 1.0]
temperature_ev = species.evaluate_input_profile("temperature", psi_n)
particle_rate = species.evaluate_input_profile("particle_source_rate", psi_n)
region_1_weight = species.deposition_shapes[1].evaluate_weight(psi_n)