Unknown layout

KineticUnknown(name, grid; scale=1, nonnegative=false, unit=nothing)

Distribution function on the kinetic grid grid, one value per momentum cell at each radius (e.g. :hot_tail_distribution). The momentum grid may differ between radii. A distribution is normally declared without a lower limit: negative values produced by the discretization belong to the scheme, not to the Newton steps. unit is the unit of its values as a string, ASCII without control characters. Without one, it is "m^-3" whatever the name, for a density per unit of momentum volume with the momentum in $m_e c$.

LowerLimit(; value=0, tolerance=0, reference=nothing)

Lower limit of an unknown, enforced on Newton steps (DREAM damps the Newton update to keep selected unknowns above a tenth of their value, MaximalPhysicalStepLength in src/Solver/SolverNonLinear.cpp:441-524): every entry stays at or above value - tolerance * reference value, where the reference value is the radial unknown reference (one component) at the same radius, or the unknown's own scale when reference is nothing, or the sum of the magnitudes of the components of the entry's group at the same radius when reference is :group (the charge states of one ion species, RadialUnknown with groups). Declared on the unknown with nonnegative = true (value 0, tolerance 0) or nonnegative = LowerLimit(...), e.g. RadialUnknown(:ion_densities; components=3, nonnegative=LowerLimit(tolerance=1e-12, reference=:total_electron_density)). Scalar unknowns take no reference. An unknown that can sit at exactly 0 (an empty charge state) needs a positive tolerance: with tolerance 0 a round-off negative update of an entry at its limit fails the Newton step (:below_lower_limit), and shorter time steps do not help.

value is an absolute limit in the units of the unknown, such as the floor of a temperature: RadialUnknown(:cold_electron_temperature; nonnegative=LowerLimit(value=0.5)). A Newton update loses at most the fraction max_reduction of the distance to the limit, so an iterate approaches the floor and does not cross it, and a step whose solution lies below it does not converge and is refused. The temperature unknown of a PlasmaFromUnknowns takes the floor of that source as its limit without a declaration, and the larger of the two values where both exist. A temperature that only fluid terms read takes the default floor DEFAULT_TEMPERATURE_FLOOR without a declaration (fluid_temperature_floors); a declared limit is kept as it is.

RadialUnknown(name; components=1, scale=1, nonnegative=false, groups=nothing, unit=nothing)

Unknown with components values at each radius (e.g. :electric_field, or :ion_densities with one component per charge state). groups splits the components into consecutive ranges, such as the charge states of each ion species (component_groups). An unknown that declares groups, even a single one, takes by default the tolerances relative to the sum over each group (tolerance, StepController). unit is the unit of its values, as of a ScalarUnknown.

ScalarUnknown(name; scale=1, nonnegative=false, unit=nothing)

Unknown with one value for the whole system (e.g. :plasma_current). scale is its reference magnitude; nonnegative declares a LowerLimit. unit is the unit of its values as a string, such as "A", which the output file stores. It is ASCII without control characters. Without one, an unknown of a default name takes the unit of the table in the section "Units of the unknowns" of the docs page "Unknowns and the equation system", and any other the empty string.

UnknownLayout(radial_grid, unknowns; scalars=:last)

Positions of the unknowns (a list of ScalarUnknown, RadialUnknown and KineticUnknown) in the state vector. Each radius owns one contiguous block, with the radial and then the kinetic unknowns in declaration order; the scalar unknowns form one block after the radius blocks (scalars = :first places it before them, which only serves to check that no code depends on the order). Kinetic unknowns must live on radial_grid. The layout is immutable; adding an unknown builds a new layout.

component_groups(unknown::RadialUnknown)

The groups of the components of a radial unknown, consecutive ranges that split 1:components: the charge states of each ion species for the ion densities (ion_densities_unknown), one group of all components otherwise. A LowerLimit with reference = :group and a Tolerance with a group part are relative to the sum over the group of an entry.

copy_unknowns!(u_to, layout_to, u_from, layout_from)

Copy the values of every unknown present in both layouts, matched by name. The sizes, the radial grid, the momentum grids of a kinetic unknown and the component groups of a radial unknown (the ion species) must agree. Two species with the same count of charge states that trade places are not detected. Returns the names copied. This is how a state is carried to a layout with another order or with unknowns added or removed (restarts).

kinetic_grid(layout, id)

Kinetic grid of the kinetic unknown id.

kinetic_view(u, layout, id, ir)

View into the state vector u of the kinetic unknown id at radius index ir, as a (p cells, ξ cells) matrix of the momentum grid there. Type-stable as radial_view.

radial_view(u, layout, id, ir)

View into the state vector u of the components of the radial unknown id at radius index ir, as a vector. Type-stable for a given u, including vectors of dual numbers, so terms use it in inner loops with ids from unknown_id. See also kinetic_view and scalar_view.

radius_block_range(layout, ir)

Contiguous index range of all unknowns at radius index ir. The per-radius preconditioner and a radial domain decomposition work on these blocks.

scalar_block_range(layout)

Contiguous index range of all scalar unknowns, the block next to those of radius_block_range.

scalar_view(u, layout, id)

View into the state vector u of the scalar unknown id, 0-dimensional. Type-stable as radial_view.

unknown(layout, id_or_name)

Declaration of an unknown (ScalarUnknown, RadialUnknown or KineticUnknown).

unknown_id(layout, name)

Integer id of the unknown name, for use in inner loops; setup code uses names.

unknown_names(layout)

Names of the unknowns in declaration order.

unknown_range(layout, id, ir)
unknown_range(layout, id)

Index range of unknown id at radius index ir (radial and kinetic unknowns), or of a scalar unknown.

unknown_scales(layout)

Vector of the reference scale of every entry of the state vector.

unknown_unit(layout, id_or_name)

Unit of the values of an unknown, the string that the output file stores with it: the unit of its declaration, or its default (the section "Units of the unknowns" of the docs page "Unknowns and the equation system"). The empty string marks an unknown without a unit.

unknown_values(u, layout, id)

LayoutRadialValues of the radial unknown id, which has one component, in the state u: its value at every radius, writable in place (unknown_values(u, layout, id) .= values). radial_view gives the components of an unknown at one radius, and unknown_view takes the unknown by name.

unknown_view(u, layout, name, ir)
unknown_view(u, layout, name)

View of the unknown name by kind (see radial_view); convenient for setup and tests, not type-stable.