solprop.recipe.pins#

Pins: a recipe value set from a design target instead of a literal (SEP 41, S1).

A recipe’s [pins] table sets a whole value from a target of solprop.tools.solve_parameter():

[pins]
pressure = {target = "zdw", wavelength = "800 nm", search = ["0.1 bar", "10 bar"]}
energy = {target = "soliton_order", order = 4}

Pins resolve in two fixed stages after the literals: at most one pin on a parameter of the guide or fill (zdw or rdw), solved on the launch mode at the launch position; then the pins on pulses (soliton_order), which read the mode the first stage settled. So no order has to be declared and no cycle can be written. solve_pin() is the solver call on a route’s own keywords, which the Python export writes before the route’s call.

Module Attributes

`PinStage`	The stage a pin resolves in: a parameter of the guide or fill, or a pulse's.
`GUIDE_PINS`	The guide and fill keywords each route can pin, and the mode parameter each sets.
`PULSE_PINS`	The pulse keywords a pin can set, on the route or on one of its `pulses`.
`TARGETS`	Each target: its stage, its required keys and its optional ones, beside `target`, `search` and `root`.

Functions

`design_target`(pin, keywords)	Return the solver's target for a guide pin.
`placeholder`(path)	Return the value a pulse pin stands at while the guide is solved.
`read_pins`(recipe)	Return a recipe's pins, checked, guide pin first.
`solve_pin`(route, keywords, path, target, search)	Solve a parameter of a route's guide or fill for a design target.
`solve_pulse`(route, keywords, path, order[, ...])	Return the energy or peak power that gives a pulse a soliton order.

Classes

Pin(path, stage, target, keys, search, root)

One entry of a recipe's [pins] table, checked.

solprop.recipe.pins.GUIDE_PINS: Final[Mapping[str, Mapping[str, str]]] = {'capillary': {'pressure': 'pressure', 'radius': 'core_radius'}}#: The guide and fill keywords each route can pin, and the mode parameter each sets.

solprop.recipe.pins.PULSE_PINS: Final = ('energy', 'peak_power')#: The pulse keywords a pin can set, on the route or on one of its pulses.

class solprop.recipe.pins.Pin(path, stage, target, keys, search, root)[source]#

Bases: object

One entry of a recipe’s [pins] table, checked.

Attributes:

pathstr: The canonical parameter path the pin sets.
stage{‘guide’, ‘pulse’}: Whether it sets a parameter of the guide or fill, or a pulse’s energy or peak power.
target{‘zdw’, ‘rdw’, ‘soliton_order’}: The design target.
keyscollections.abc.Mapping: The target’s keys, numbers in SI.
searchtuple of float or None: The search range in the pinned keyword’s unit; None for a pulse pin without one.
root{‘lowest’, ‘highest’} or int: Which root, where there are several.

keys: Mapping[str, object]#

path: str#

root: RootChoice#

search: tuple[float, float] | None#

stage: PinStage#

target: str#

type solprop.recipe.pins.PinStage = Literal['guide', 'pulse']#: The stage a pin resolves in: a parameter of the guide or fill, or a pulse’s.

solprop.recipe.pins.TARGETS: Final[Mapping[str, tuple[PinStage, tuple[str, ...], tuple[str, ...]]]] = {'rdw': ('guide', ('rdw',), ('peak_power', 'fwhm', 'shape', 'nonlinear_phase')), 'soliton_order': ('pulse', ('order',), ()), 'zdw': ('guide', ('wavelength',), ())}#: Each target: its stage, its required keys and its optional ones, beside target, search and root.

solprop.recipe.pins.design_target(pin, keywords)[source]#

Return the solver’s target for a guide pin.

Parameters:

pinPin: A zdw or rdw pin.
keywordscollections.abc.Mapping: The route’s keywords, for the pump wavelength.

Returns:

ZDW or RDW: The target.

solprop.recipe.pins.placeholder(path)[source]#

Return the value a pulse pin stands at while the guide is solved.

Parameters:

pathstr: The pulse pin’s path.

Returns:

float: An energy of 1 uJ or a peak power of 1 MW, in SI.

solprop.recipe.pins.read_pins(recipe)[source]#

Return a recipe’s pins, checked, guide pin first.

Parameters:

recipeRecipe: The recipe.

Returns:

tuple of Pin: The pins, the one on the guide or fill (if any) first.

Raises:

RecipeError: On the pinned path, if a pin sets a value the route cannot pin, an element of an array, a path also set literally, or a second guide or fill parameter; or if its target, keys, search range or root do not read. On the object routes, which have no mode to solve a target on, any pin.

solprop.recipe.pins.solve_pin(route, keywords, path, target, search)[source]#

Solve a parameter of a route’s guide or fill for a design target.

The route is built once from keywords, with the parameter at the middle of search, and its launch mode is re-evaluated at each trial value (no further builds), as solprop.tools.pressure_zdw() does; a target that needs the fill’s Kerr coefficient is given it at each trial value. This is the call the Python export of a pinned recipe writes before the route’s call.

Parameters:

routestr: The route, such as "capillary".
keywordscollections.abc.Mapping: The route’s keywords, without the one solved for.
pathstr: The keyword solved for, one of GUIDE_PINS for the route.
targetZDW or RDW: The target.
searchtuple of float: The search range, in the keyword’s unit (bar for a pressure, m for a radius).

Returns:

solprop.tools.DesignRoots: Every root in the range, or none with the attainable range.

Raises:

RecipeError: If the keyword cannot be pinned on the route, or the route does not build with it at the middle of the range.

Examples

>>> from solprop.recipe.pins import solve_pin
>>> from solprop.tools import ZDW
>>> keywords = dict(radius=125e-6, gas="He", length=1.0, wavelength=800e-9,
...                 fwhm=10e-15, trange=400e-15, wavelength_limits=(130e-9, 4e-6))
>>> roots = solve_pin("capillary", keywords, "pressure", ZDW(500e-9), (0.01, 10.0))
>>> f"{roots.pick('lowest'):.3f} bar"
'1.278 bar'

solprop.recipe.pins.solve_pulse(route, keywords, path, order, search=None)[source]#

Return the energy or peak power that gives a pulse a soliton order.

Closed form on the launch mode at the launch position, with the fill’s Kerr coefficient (solprop.tools.soliton_peak_power()). The route is built once, the pulse at a placeholder, for its mode. This is the call the Python export of a recipe with a soliton_order pin writes before the route’s call.

Parameters:

routestr: The route, such as "capillary".
keywordscollections.abc.Mapping: The route’s keywords. For a route-level path ("energy" or "peak_power") without it; for "pulses[i].energy" with the pulse built at any energy, which is not read.
pathstr: The pulse value solved for.
orderfloat: The conventional soliton order, > 0.
searchtuple of float or None, optional: A range the value must lie in, in its unit (J or W); None for any.

Returns:

solprop.tools.DesignRoots: The one value, or none with it as the attainable range when it lies outside search.

Raises:

RecipeError: If the pulse is not a sech or ordinary Gaussian pulse, the dispersion at its wavelength is not anomalous, or the route does not build.

Examples

>>> from solprop.recipe.pins import solve_pulse
>>> keywords = dict(radius=125e-6, gas="He", pressure=0.5, length=1.0,
...                 wavelength=800e-9, fwhm=10e-15, trange=400e-15,
...                 wavelength_limits=(130e-9, 4e-6))
>>> roots = solve_pulse("capillary", keywords, "energy", 3.0)
>>> f"{roots.pick() * 1e6:.1f} uJ"
'348.3 uJ'