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
The units of an array keyword whose elements differ, as a function of the index. |
Functions
|
Return the unit of element |
|
Write a value in |
|
Read a recipe value given as a number or a quantity string, in |
|
Return the unit of element |
Classes
|
A physical dimension as integer exponents of five base dimensions. |
|
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:
objectA 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)'
- 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:
objectThe 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
textcannot be read, or isdeg(a keyword’s unit israd).
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'
- solprop.recipe.quantity.beta_unit(order)[source]#
Return the unit of element
orderof abetaslist.The propagation constant’s Taylor coefficients
β_n = ∂ⁿβ/∂ωⁿare in sⁿ/m.- Parameters:
- orderint
The Taylor order
n, at least 0.
- Returns:
- Unit
1/mfor order 0,s/mfor order 1 ands^n/mafter.
- Raises:
- RecipeError
If
orderis 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
unitas a quantity string in the display unit.The number has the fewest significant digits that read back, through
parse_quantity(), to exactlyvalue, 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
valueis not finite, ordisplaycannot 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
intorfloat, taken inunit, 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 dimensionlessunit.- 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
valueis 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
orderof aphaseslist.The spectral phase is the Taylor series
Σ φ_n (ω - ω₀)ⁿ / n!, soφ_0is an angle andφ_nforn ≥ 1is 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
radfor order 0,sfor order 1 ands^nafter.
- Raises:
- RecipeError
If
orderis negative.
Examples
>>> [phase_unit(n).text for n in range(4)] ['rad', 's', 's^2', 's^3']