Process reference: species

Generated from the docstrings of vaft.process.species: 4 public functions. Each entry is what vaft.process.describe("species.<name>") prints. All process categories

Overview

One physical plasma state is not one species representation. This module keeps the most explicit composition a product supports – every component a nuclide in one charge state and one kinetic population – and derives reduced representations only at a physics boundary, each with an explicit record of what it preserves and what it does not. The algebra is vaft.formula.impurity; impurity composition (which mixture applies) is vaft.process.impurity (#1565). This module adds the axes those two do not have – kinetic population, an explicit basis for every dilution, and the projection contract.

The chain::

core_profiles ion[] / state[] / density_fast    (species_state_from_core_profiles)
#1565 resolved or radial composition            (species_state_from_composition)
    -> CanonicalSpeciesState: components = nuclide x charge state x population
    -> composition_moments: n_e(sum Z n), Z_eff, charge fractions by NAMED basis
    -> project_species_state(target_physics) -> SpeciesProjection
           (components for the solver + preserved / not_guaranteed / source ids)
SymbolMeaningUnit
aone component (nuclide, charge state, population)-
Z_acharge of component a (a bundle average <Z> where bundled)-
n_adensity of component am^-3
f_basissum_{a in basis} Z_a n_a / n_e, the charge fraction of a basis [-]

Component identity is not a solver index. component_id names the physics (D-2/Z1/thermal); a solver’s species list is whatever a projection hands it, and two projections of one state are distinct model cases even when they share state_id.

Every dilution names its basis. thermal_main (thermal hydrogen isotopes), fuel (hydrogen isotopes in any population), impurity (Z_n > 1, any population), fast_ion (every non-thermal population). There is no unqualified dilution.

Fast populations stay distinct. A thermal and a fast population of one isotope and charge are two components; they add in charge bookkeeping and are never merged into one Maxwellian by a projection.

Functions

composition_momentsComposition moments of a species state, every dilution with its basis named. Convention
project_species_stateThe species representation one target physics receives, with its conservation contract. Convention
species_state_from_compositionThe canonical species state a #1565 composition implies for a given electron density. Convention
species_state_from_core_profilesThe canonical species state of one core_profiles slice, read without creating paths. Convention

composition_moments

Machine-independentConvention-sensitive source 
composition_moments(state)
Show source vaft/process/species.py, lines 683–733 
def composition_moments(state: CanonicalSpeciesState) -> dict[str, Any]:
    """Composition moments of a species state, every dilution with its basis named.

    Parameters
    ----------
    state : CanonicalSpeciesState
        The canonical state [any].

    Returns
    -------
    dict
        ``n_e_quasineutral`` [m^-3], ``quasineutrality_residual`` (relative to the
        stored n_e, or ``None``), ``zeff`` [-], and for every basis of
        :data:`BASES` ``fraction_<basis>`` = sum Z n / n_e [-]; plus
        ``dilution_thermal_main`` and ``dilution_fuel`` = 1 - the main
        fractions [-] [any].

    Convention
    ----------
    Fractions are charge fractions over the stored n_e when known (else the
    quasi-neutral sum): ``fraction_thermal_main + fraction_impurity +`` the
    fast hydrogenic share add to one only for a quasi-neutral state.  Z_eff
    uses ``<Z^2>`` for a bundled component, never ``<Z>^2``.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [issue] #1567 Sec. 3, #1565 dilution comment.
    """
    ne = state.electron_density()
    charge = state.charge_density()
    with np.errstate(invalid="ignore", divide="ignore"):
        out: dict[str, Any] = {
            "n_e_quasineutral": charge,
            "quasineutrality_residual": None if state.n_e is None else (charge - state.n_e) / state.n_e,
            "zeff": np.sum([c.density * c.z_moment(2) for c in state.components], axis=0) / ne,
        }
        for basis in BASES:
            chosen = state.select(basis)
            out[f"fraction_{basis}"] = (np.sum([c.density * c.z_moment(1) for c in chosen], axis=0) / ne
                                        if chosen else np.zeros(state.size))
    out["dilution_thermal_main"] = 1.0 - out["fraction_thermal_main"]
    out["dilution_fuel"] = 1.0 - out["fraction_fuel"]
    out["basis_definitions"] = {
        "thermal_main": "thermal hydrogen isotopes", "fuel": "hydrogen isotopes, any population",
        "impurity": "Z_n > 1, any population", "fast_ion": "every non-thermal population",
    }
    return out

Composition moments of a species state, every dilution with its basis named.

NameTypeUnitDescription
stateCanonicalSpeciesStateany

The canonical state.
Returns
—dictany

n_e_quasineutral [m^-3], quasineutrality_residual (relative to the stored n_e, or None), zeff [-], and for every basis of BASES fraction_<basis> = sum Z n / n_e [-]; plus dilution_thermal_main and dilution_fuel = 1 - the main fractions [-].

Convention

Fractions are charge fractions over the stored n_e when known (else the quasi-neutral sum): fraction_thermal_main + fraction_impurity + the fast hydrogenic share add to one only for a quasi-neutral state. Z_eff uses <Z^2> for a bundled component, never <Z>^2.

Applicability · Provenance

Applicability

Machine-independent.

Provenance

  1. #1567 Sec. 3, #1565 dilution comment.

project_species_state

Machine-independentConvention-sensitive source 
project_species_state(state, target_physics, method=None)

The species representation one target physics receives, with its conservation contract.

NameTypeUnitDescription
stateCanonicalSpeciesStateany

The canonical state.

target_physicsstr-

One of PROJECTION_POLICY (quasineutrality, resistive, classical, neoclassical, turbulence, gyrokinetic, atomic, fusion).

methodstr, optional-

A method the target allows; default the target’s own.
Returns
—SpeciesProjectionany

Components for the solver, the source component ids, what is preserved and what is not guaranteed, the moments, and state_id / projection_id.

Convention

#1567 Sec. 5: the representation follows the physics operator, never a global convenience. Same Z_eff does not mean same neoclassical or gyrokinetic response, so neoclassical and gyrokinetic allow only explicit.

Raises

  • ValueError An unknown target, a method the target does not allow (for example an effective impurity for NEO), or a charge-state projection of a state whose components are bundled.
Processing steps · Applicability · Limitations · Provenance

Processing steps

  1. Look up the target’s default and allowed methods.
  2. explicit: every component; moments_only: no components, the moments; effective_impurity: fuel and fast kept, thermal impurities reduced on their Z and Z^2 moments with a mass profile; charge_state_resolved: refuse a bundled component; fusion: hydrogen isotopes and 3He kept per population, the other impurities reduced.
  3. Attach the method’s preserves / not_guaranteed and the moments.

Applicability

Machine-independent.

Limitations

No solver-specific readiness here (that stays with each solver, #1428); phase-space detail of fast populations lives in distributions (#1216).

Provenance

  1. #1567 Sec. 4-7.

species_state_from_composition

Machine-independentConvention-sensitive source 
species_state_from_composition(composition, n_e, *, rho=None, time=None, main_isotope=None)

The canonical species state a #1565 composition implies for a given electron density.

NameTypeUnitDescription
compositionResolvedImpurityComposition or RadialImpurityCompositionany

From vaft.process.impurity.

n_efloat or array-likem^-3

Electron density on the composition’s grid.

rhoarray-like, optional-

The grid; default the composition’s own (a radial composition refuses any other).

timefloat, optionals

Slice time; default the composition’s own.

main_isotopeint, optional-

Mass number (1, 2 or 3) of a main ion the composition names only as H; refused when it names D, T or another element.
Returns
—CanonicalSpeciesStateany

The thermal main ion and, for a radial composition, one component per ionised charge state of every element (the most explicit form); for a resolved composition, one per species – a bundle carrying the composition’s <Z>(rho) / <Z^2>(rho) where it resolved a bundled ion (mean_charge / mean_square_charge).

Convention

The origin of every component is the composition’s kind (assumed, explicit, derived, inferred); explicit is recorded as assumed, as the #1565 writers do. The main ion and its charge are the composition’s own (H/D/T, or e.g. He with charge 2). A resolved species’ charge_state is only its label: the component’s charge is the composition’s radial <Z> moment where one exists, and a non-integer label without moments is a bundle at that scalar charge.

Raises

  • ValueError A main isotope outside 1-3 or given for a named main ion, an unknown main ion, a grid other than a radial composition’s own, an n_e other than the one its charge states were computed with, or an unknown composition type.
Applicability · Provenance

Applicability

Machine-independent.

Provenance

  1. #1567 Sec. 3, #1565.

species_state_from_core_profiles

Machine-independentConvention-sensitive source 
species_state_from_core_profiles(ods, *, time=None, tolerance=0.0005)

The canonical species state of one core_profiles slice, read without creating paths.

NameTypeUnitDescription
odsODSany

Source; read with non-mutating accessors only.

timefloat, optionals

Slice time; required when the IDS holds several slices.

tolerancefloat, optionals

Largest |t_slice - time| accepted.
Returns
—CanonicalSpeciesStateany

One component per stored ion[].state[] with a density, else one per ion (bundled when it carries z_ion_1d); a non-zero density_fast becomes a separate fast_unspecified component; n_e from the electrons.

Convention

IMAS density_fast does not say what made the fast ions, so the population is fast_unspecified; a caller that knows (NUBEAM) relabels it.

Raises

  • ValueError No slice at the time, no electron density, or an ion without a nuclear charge or charge state.
Processing steps · Input semantics · Output semantics · Applicability · Limitations · Provenance

Processing steps

  1. Match the slice by time; read rho_tor_norm and n_e.
  2. Per ion: nuclide from element.0.z_n/a (hydrogen isotopes by mass); origin from density_fit.parameters (#1565 record grammar).
  3. Stored charge states become components (a state spanning several charges is a bundle with its z_average_1d/z_average_square_1d (or the scalar z_average/z_square_average), its own temperature when stored); otherwise the ion is one component – bundled with z_ion_1d/z_ion_square_1d when present. A share of the ion density its states do not carry, and a z_ion_square_1d stored on an ion of one integer charge state (ignored: <Z^2> = Z^2 there), are reported in the provenance notes.
  4. At every level, density_thermal (or density - density_fast) is the thermal component and density_fast a separate fast one; an ion-level density_fast is kept even when the states carry none.
  5. n_e is the total electrons.density (falling back to the thermal one), since the ion charge counts fast ions too.

Input semantics

A core_profiles slice, measured, fitted or written by a composition model.

Output semantics

The same composition as components with explicit identity and population.

Applicability

Machine-independent.

Limitations

A fast component takes no temperature (its distribution is not Maxwellian); distributions (#1216) remains authoritative for it.

Provenance

  1. #1567 Sec. 1-2, #1565 (origin records).

API

results matching ""

    No results matching ""