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. .. list-table:: Input-defined profile coverage :header-rows: 1 :widths: 24 16 16 16 28 * - Inputs / Python key - Scope - Values / units - Shape IDs - Parameters and defaults * - ``eq_dens_*`` / ``density`` - per species - density, m⁻³ - -1, 0, 1, 2, 5 - ``v1=1e20``; remaining ``v1..3``, ``x1..3`` default 0 * - ``eq_temp_*`` / ``temperature`` - per species - temperature, eV - same - ``v1=1e3``; other coefficients default 0 * - ``eq_flow_*`` / ``flow`` - per species - raw flow, m/s for type 0; rad/s for types 1/2 - same - coefficients default 0; ``eq_flow_type=2`` * - ``eq_dens_diff_*`` / ``ptl_diffusivity`` - per species - m²/s - same - coefficients default 0 * - ``eq_flow_diff_*`` / ``momentum_diffusivity`` - per species - m²/s - same - coefficients default 0 * - ``eq_t_diff_*`` / ``heat_conductivity`` - per species - m²/s - same - coefficients default 0 * - ``eq_pinch_v_*`` / ``ptl_pinch_velocity`` - per species - m/s - same - coefficients default 0 * - ``eq_fg_temp_*``, ``eq_mk_temp_*`` / ``fgrid_temperature``, ``marker_temperature`` - per species - eV - same - inherit ``eq_temp`` shape, coordinates, values, and file unless overridden * - ``eq_fg_flow_*``, ``eq_mk_flow_*`` / ``fgrid_flow``, ``marker_flow`` - per species - m/s or rad/s according to their flow type - same - inherit ``eq_flow`` shape, coordinates, values, file, and flow type * - ``src_particle_source_*`` / ``particle_source_rate`` - per species - m⁻³ s⁻¹ - same - ``v1..4``, ``x1..5`` default 0; file defaults to ``example.dat`` * - ``eq_zeff_*`` / ``Simulation.prescribed_profiles['effective_charge']`` - run-wide, when ``rad_use_zeff_profile`` - dimensionless - same - ``v1..3=1``, ``x1=1``, ``x2=0.1``, ``x3=0``; file ``zeff.dat`` * - ``src_ishape1..4`` with ``src_pin*``, ``src_pout*``, ``src_decay_width*``, ``src_special_mode*`` / ``Species.deposition_shapes`` - per species and region - unnormalized weight, dimensionless or m - 1 trapezoid, 2 Gaussian - ``src_narea`` defaults to 1 for main ion, 0 otherwise; region geometry defaults are in XGC's ``heat_torque.cpp`` 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)