solprop.recipe.quantity#

Quantities in a recipe: numbers with units, read and written back exactly.

A recipe value is either a bare number, taken in the keyword’s own unit, or a quantity string such as "125 um", "1.2 bar" or "2e14 W/cm^2", converted to that unit. The keyword’s unit is the one its docstring states, so pressures stay in bar (docs/dev/conventions.md) and a bare 1.2 for a pressure means 1.2 bar. Unit is a parsed unit, its Dimension tracking plane angle as a fifth base dimension beside length, time, mass and temperature; phase_unit() and beta_unit() are the per-order units of phases and betas. parse_quantity() converts exactly in decimal with one rounding to binary64, and format_quantity() writes a double in a display unit with the fewest digits that read back to it. The unit grammar, and why the conversion and the writing back are exact (deg included), are in the manual, docs/guide/setup/recipes.md (“Values”).

Module Attributes

ElementUnits

The units of an array keyword whose elements differ, as a function of the index.

Functions

beta_unit(order)

Return the unit of element order of a betas list.

format_quantity(value, unit, display)

Write a value in unit as a quantity string in the display unit.

parse_quantity(value, unit, *[, path])

Read a recipe value given as a number or a quantity string, in unit.

phase_unit(order)

Return the unit of element order of a phases list.

Classes

Dimension([length, time, mass, temperature, ...])

A physical dimension as integer exponents of five base dimensions.

Unit(text)

The unit a keyword, or an element of one, is given in.

class solprop.recipe.quantity.Dimension(length=0, time=0, mass=0, temperature=0, angle=0)[source]#

Bases: object

A physical dimension as integer exponents of five base dimensions.

Attributes:
lengthint

Exponent of length (m).

timeint

Exponent of time (s).

massint

Exponent of mass (kg).

temperatureint

Exponent of thermodynamic temperature (K).

angleint

Exponent of plane angle (rad), kept apart so that rad/s and Hz differ.

Examples

>>> pressure = Dimension(length=-1, time=-2, mass=1)
>>> str(pressure)
'pressure (kg m^-1 s^-2)'
>>> str(Dimension(length=1) * Dimension(length=1))
'area (m^2)'
angle: int = 0#
length: int = 0#
mass: int = 0#
temperature: int = 0#
time: int = 0#
type solprop.recipe.quantity.ElementUnits = Callable[[int], Unit]#

The units of an array keyword whose elements differ, as a function of the index.

class solprop.recipe.quantity.Unit(text)[source]#

Bases: object

The unit a keyword, or an element of one, is given in.

A bare number for the keyword is taken in this unit, and every quantity string is converted to it. It is a decimal multiple of an SI unit, usually the coherent one ("m", "s^2/m") but "bar" for a pressure.

Attributes:
textstr

The unit in the grammar of the module docstring, in ASCII, or "1" for a dimensionless keyword. Two units are equal when their texts are.

Raises:
RecipeError

If text cannot be read, or is deg (a keyword’s unit is rad).

Examples

>>> Unit("bar").dimension
Dimension(length=-1, time=-2, mass=1, temperature=0, angle=0)
>>> str(Unit("s^2/m").dimension)
'm^-1 s^2'
property dimension: Dimension[source]#

The unit’s dimension.

The exponents of the five base dimensions.

text: str#
solprop.recipe.quantity.beta_unit(order)[source]#

Return the unit of element order of a betas list.

The propagation constant’s Taylor coefficients β_n = ∂ⁿβ/∂ωⁿ are in sⁿ/m.

Parameters:
orderint

The Taylor order n, at least 0.

Returns:
Unit

1/m for order 0, s/m for order 1 and s^n/m after.

Raises:
RecipeError

If order is negative.

Examples

>>> [beta_unit(n).text for n in range(4)]
['1/m', 's/m', 's^2/m', 's^3/m']
solprop.recipe.quantity.format_quantity(value, unit, display)[source]#

Write a value in unit as a quantity string in the display unit.

The number has the fewest significant digits that read back, through parse_quantity(), to exactly value, the sign of a zero included.

Parameters:
valuefloat

The value in unit; finite.

unitUnit

The keyword’s unit.

displaystr

The unit to write in, of the same dimension, in ASCII by convention ("um").

Returns:
str

A quantity string such as "125 um".

Raises:
RecipeError

If value is not finite, or display cannot be read or is of another dimension.

Examples

>>> format_quantity(125e-6, Unit("m"), "um")
'125 um'
>>> format_quantity(7.5e-15, Unit("s"), "fs")
'7.5 fs'
>>> format_quantity(1.2, Unit("bar"), "kPa")
'120 kPa'
solprop.recipe.quantity.parse_quantity(value, unit, *, path=None)[source]#

Read a recipe value given as a number or a quantity string, in unit.

Parameters:
valueobject

An int or float, taken in unit, or a string of a decimal number and a unit ("125 um", "2e14 W/cm^2"), whose dimension must be the unit’s. A string with no unit is read only for a dimensionless unit.

unitUnit

The keyword’s unit.

pathstr or None, optional

The parameter path, for the error message.

Returns:
float

The value in unit: the double nearest the exact decimal value.

Raises:
RecipeError

If value is a boolean, not finite, not a number or quantity string, or of another dimension, if its unit cannot be read or has two readings, or if the value overflows or underflows a double.

Examples

>>> parse_quantity("800 nm", Unit("m")) == 800e-9
True
>>> parse_quantity("120 kPa", Unit("bar"))
1.2
>>> parse_quantity(1.2, Unit("bar"))
1.2
>>> parse_quantity("2e14 W/cm^2", Unit("W/m^2"))
2e+18
solprop.recipe.quantity.phase_unit(order)[source]#

Return the unit of element order of a phases list.

The spectral phase is the Taylor series Σ φ_n (ω - ω₀)ⁿ / n!, so φ_0 is an angle and φ_n for n ≥ 1 is in sⁿ (the radian of the phase is not carried into the higher orders, as is usual for dispersion coefficients).

Parameters:
orderint

The Taylor order n, at least 0.

Returns:
Unit

rad for order 0, s for order 1 and s^n after.

Raises:
RecipeError

If order is negative.

Examples

>>> [phase_unit(n).text for n in range(4)]
['rad', 's', 's^2', 's^3']