solprop.recipe.metadata#

Machine-readable metadata of every keyword a recipe can set (SEP 41, S9).

One Parameter per keyword of a route’s Simulation.from_* constructor, of its prop_* function and of the execution settings: its forms (a keyword often takes several, as pressure takes a number, a gradient or a profile), their units and ranges, whether it needs the "none" spelling, the unit a front end shows it in, whether the resolved recipe writes it back, the rule that resolves a None default, and where it is documented. The function’s signature stays the single source of the default: parameters() reads it, and a test holds the table and the signature to the same names.

A front end’s tooltips and field validation come from this table; its labels and wording are its own.

Module Attributes

`FormKind`	What a form of a keyword holds.
`Group`	Where a front end shows a keyword.
`Level`	Whether a newcomer sees a keyword, or only an expert.
`ElementUnits`	Keywords whose elements carry different units (SEP 41 section 4).
`REQUIRED`	The default `parameters()` records for a keyword the caller must give.
`OBJECT_ROUTES`	The routes whose `[build]` keywords are objects: grids, medium, beam and settings.
`SETTINGS_KEYWORDS`	Keywords of an object route's constructor that a recipe writes under `settings`.
`Resolver`	Given the values a recipe sets, return what a `None` default resolves to.
`PER_WIDTH_KEYWORDS`	The keywords that are per metre of y on a slab mode set (`per_unit_width()`).

Functions

`parameters`(route)	Return the metadata of a route's build keywords, with their defaults.
`per_unit_width`(route, values)	Return whether a recipe's pulse energy and peak power are per metre of y.
`surface`(route)	Return the constructor whose keywords a route's `[build]` table holds.

Classes

`Form`(kind[, unit, elements, minimum, ...])	One form a keyword's value may take.
`Parameter`(name, forms, group, level, ...[, ...])	Everything a front end needs to show and check one keyword.
`Resolution`(value, rule)	The value a `None` default will take, and the rule that chose it.

solprop.recipe.metadata.ElementUnits#

Keywords whose elements carry different units (SEP 41 section 4).

phases is [rad, s, s^2, ...]; betas is s^n/m for order n; the (z, p) form of pressure is two rows, positions in metres and pressures in bar.

alias of Literal[‘phases’, ‘betas’, ‘z_pressure’]

class solprop.recipe.metadata.Form(kind, unit=None, elements=None, minimum=None, maximum=None, exclusive=False, choices=(), types=(), length=None, recipe=True)[source]#

Bases: object

One form a keyword’s value may take.

Attributes:

kindstr: A FormKind.
unitstr or None: The keyword’s own unit, in which a bare number is read: SI, except that pressures are in bar (docs/dev/conventions.md). None for a number with no unit, and for the non-numeric kinds.
elements{‘phases’, ‘betas’} or None: For an array whose elements carry different units, which rule gives them.
minimum, maximumfloat or None: The allowed range, inclusive unless exclusive says otherwise.
exclusivebool: Whether the range’s ends are excluded.
choicestuple of str: The allowed values of a "choice".
typestuple of str: The registered types an "object" may name.
lengthint or None: The number of elements of a "pair" or fixed-length array.
recipebool: Whether a recipe can hold this form; False for a callable or an object type that is not registered, which only the Python export carries.

Examples

>>> from solprop.recipe.metadata import Form
>>> Form("number", unit="m", minimum=0.0, exclusive=True).recipe
True

choices: tuple[str, ...] = ()#

elements: Literal['phases', 'betas', 'z_pressure'] | None = None#

exclusive: bool = False#

kind: Literal['number', 'integer', 'boolean', 'choice', 'string', 'pair', 'array', 'mapping', 'object', 'callable']#

length: int | None = None#

maximum: float | None = None#

minimum: float | None = None#

recipe: bool = True#

types: tuple[str, ...] = ()#

unit: str | None = None#

solprop.recipe.metadata.FormKind#

What a form of a keyword holds.

"number" a real number or quantity string; "integer" an integer (a decimal string for one beyond 64 bits); "boolean"; "choice" one of fixed strings; "string" free text, such as a gas name; "pair" two numbers; "array" a one-dimensional list of numbers or a data file; "mapping" a table keyed by name; "object" a registered type, written as a table with a type key; "callable" a Python function, which no recipe holds (the Python export is the way out).

alias of Literal[‘number’, ‘integer’, ‘boolean’, ‘choice’, ‘string’, ‘pair’, ‘array’, ‘mapping’, ‘object’, ‘callable’]

solprop.recipe.metadata.Group#

Where a front end shows a keyword.

alias of Literal[‘geometry’, ‘medium’, ‘nonlinear’, ‘input’, ‘grid’, ‘numerics’, ‘output’]

solprop.recipe.metadata.Level#

Whether a newcomer sees a keyword, or only an expert.

alias of Literal[‘basic’, ‘advanced’]

solprop.recipe.metadata.OBJECT_ROUTES: Final = ('radial', 'free', 'planar')#

The routes whose [build] keywords are objects: grids, medium, beam and settings.

Their Simulation.from_* takes the time grid, the transverse grid, the medium, the responses and the beam positionally, and the stepping in a settings object; a recipe writes each as a table under its keyword’s name.

solprop.recipe.metadata.PER_WIDTH_KEYWORDS: Final = ('energy', 'peak_power')#: The keywords that are per metre of y on a slab mode set (per_unit_width()).

class solprop.recipe.metadata.Parameter(name, forms, group, level, summary, anchor, display=None, none=False, resolvable=False, resolver=None, default=REQUIRED)[source]#

Bases: object

Everything a front end needs to show and check one keyword.

Attributes:

namestr: The keyword.
formstuple of Form: The forms its value may take; None is a form wherever the default is None or none is set.
groupstr: A Group.
levelstr: A Level.
summarystr: One line.
anchorstr: The manual section, as a path under docs/ with an optional #anchor.
displaystr or None: The unit a front end shows and a canonical recipe writes, in ASCII ("um", "fs"); None for no unit.
nonebool: Whether the keyword’s default is not None yet it accepts None, so a recipe spells None as the string "none" (SEP 41 section 5.1).
resolvablebool: Whether the resolved recipe writes the value that was used (SEP 41 section 5.2): only where writing it back gives the same record.
resolvercallable or None: For a None default resolved by a rule, the function that says what it resolves to (Resolver).
defaultobject: The function’s default, filled in by parameters() from the signature; REQUIRED for a keyword the caller must give.

Examples

>>> from solprop.recipe import metadata
>>> table = metadata.parameters("capillary")
>>> table["pressure"].display, table["pressure"].forms[0].unit
('bar', 'bar')

anchor: str#

default: object = REQUIRED#

display: str | None = None#

forms: tuple[Form, ...]#

group: Literal['geometry', 'medium', 'nonlinear', 'input', 'grid', 'numerics', 'output']#

level: Literal['basic', 'advanced']#

name: str#

none: bool = False#

resolvable: bool = False#

resolver: Callable[[Mapping[str, object]], Resolution] | None = None#

summary: str#

solprop.recipe.metadata.REQUIRED: Final = REQUIRED#: The default parameters() records for a keyword the caller must give.

class solprop.recipe.metadata.Resolution(value, rule)[source]#

Bases: object

The value a None default will take, and the rule that chose it.

Attributes:

valueobject: The value the build will use.
rulestr: The rule, in a sentence a front end can show.

Examples

>>> from solprop.recipe.metadata import Resolution
>>> Resolution(1e-6, "the capillary's default").value
1e-06

rule: str#

value: object#

solprop.recipe.metadata.Resolver#

Given the values a recipe sets, return what a None default resolves to.

alias of Callable[[Mapping[str, object]], Resolution]

solprop.recipe.metadata.SETTINGS_KEYWORDS: Final = ('absorber', 'absorber_scheme')#

Keywords of an object route’s constructor that a recipe writes under settings.

prop_radial, prop_free and prop_planar apply them to their settings; a recipe holds the from_* form, so they are keywords of its settings table (SEP 41 section 5.1), and the route’s table does not list them.

solprop.recipe.metadata.parameters(route)[source]#

Return the metadata of a route’s build keywords, with their defaults.

Parameters:

routestr: A route of solprop.recipe.core.ROUTES, "execution" for the [execution] table’s keys, or a registered type’s name (solprop.recipe.registry.REGISTRY) for the keywords of its table.

Returns:

collections.abc.Mapping: Parameter by keyword, in the constructor’s order, each with the default its signature declares (REQUIRED where it has none). An object route’s table leaves out SETTINGS_KEYWORDS, which a recipe writes under settings; a type’s leaves out what it receives as its build context and the keywords a recipe may not give (omitted).

Examples

>>> from solprop.recipe.metadata import parameters
>>> table = parameters("gnlse")
>>> table["rtol"].default is None, table["rtol"].resolver({}).value
(True, 1e-07)
>>> parameters("execution")["fields"].default
'all'
>>> pulse = parameters("GaussianPulse")
>>> pulse["fwhm"].display, pulse["m"].default
('fs', 1)

solprop.recipe.metadata.per_unit_width(route, values)[source]#

Return whether a recipe’s pulse energy and peak power are per metre of y.

A slab mode set is uniform in y, a plane wave in the free direction, so on the waveguide route with slab modes the PER_WIDTH_KEYWORDS are read in J/m and W/m though written, as everywhere, in J and W: the value is the same number, and a front end shows the unit per metre.

Parameters:

routestr: The route.
valuescollections.abc.Mapping: The recipe’s [build] values, as it gives them (modes as tables).

Returns:

bool: Whether the route is the waveguide’s and its mode set a slab set.

Examples

>>> from solprop.recipe.metadata import per_unit_width
>>> per_unit_width("waveguide", {"modes": {"type": "ModeCollection.slab"}})
True
>>> per_unit_width("waveguide", {"modes": [{"type": "RectMode"}]})
False

solprop.recipe.metadata.surface(route)[source]#

Return the constructor whose keywords a route’s [build] table holds.

Parameters:

routestr: The route, one of solprop.recipe.core.ROUTES.

Returns:

callable: The route’s Simulation.from_*: from_gnlse, from_capillary, from_waveguide, from_radial, from_free or from_planar.

Raises:

DriverError: If the route has no recipe yet.

Examples

>>> from solprop.recipe.metadata import surface
>>> surface("gnlse").__name__
'from_gnlse'