finesse.parameter module

class finesse.parameter.EnumCaster(enum, validate)

Bases: object

Enums are irritating as they don’t act like normal types. You need to getitem to go from value to key. They also don’t cast themselves back to themselves as float(1.0) would.

class finesse.parameter.GeometricParameter(parameter_info, owner)

Bases: Parameter

Specialised parameter class for variables which are dependencies of ABCD matrices. These include surface radii of curvature, lens focal lengths, beamsplitter angles of incidence, space lengths and space refractive indices.

When setting the value of a GeometricParameter outside of a simulation, the dependent ABCD matrices get updated via the update_abcd_matrices C method. Inside a simulation, the ABCD matrix elements are updated in a much more efficient way via the connector workspaces.

value

class finesse.parameter.Parameter(parameter_info, owner)

Bases: object

change_count

changeable_during_simulation

True if this parameter cannot be changed during a simulation.

check_dof_setters(self) → tuple[bool, Symbol | float]

Checks whether the current value is still consistent with symbolics imposed by this parameters external setters. The value can become inconsistent when users manually override the value of this parameter using the python API.

Returns

tuple[bool, Symbol]

Boolean indicating whether current value is consistent, value that would be consistent with the current external setters

datatype

The underlying C datatype of this parameter.

datatype_cast(self, value, ignore_failure=False)

Casts a value into the datatype of this parameter.

If ignore_failure is True then if this value cannot be cast it is just returned.

depends_on(self, other: Parameter | ParameterRef) → bool

Check whether this parameter symbolically depends on another parameter

description

dof_setters

eval(self, bool keep_changing_symbols=False)

Evaluates the value of this parameter.

If the parameter is dependant on some symbolic statement this will evaluate that. If it is not the value itself is returned. This method should be used when filling in matrices for computing solutions of a model.

eval_string

Whether to cal ‘eval’ on the parameter value in the string representation

full_name

is_changing

True if this parameter will be changing during a simulation.

is_controlled_by_dof

Whether this parameter is being controlled by any degrees of freedom.

is_default_for_owner

Whether this parameter is the default for the owning model element.

is_geometric

is_nr

is_symbolic

True if this parameter’s value is symbolic.

is_tunable

True if this parameter will be directly changed during a simulation.

lambdify(self, *args)

Returns a lambda function that returns the value of this parameter.

Parameters in a symbolic function can be kept as variables by passing the Parameter object as optional arguments. The returned lambda function will then have len(args) arguments - effectively subsituting values at call time.

lock(self, str by) → void

Lock this parameter, preventing it’s value from being updated until you call unlock. Note this has no effect when actually running a simulation, there parameters will be locked/unlocked depending on which parameters are changing.

lock_toggled_by

Parameter.lock_toggled_by: list[str]

Names of the object that toggled the lock on this parameter

locked

Parameter.locked: bool

If locked, this parameters value cannot be changed.

name

owner

The component/element this parameter is associated with, this could be a finesse.element.ModelElement or a finesse.model.Model.

ref

Returns a reference to this parameter’s value to be used in symbolic expressions.

remove_dof_setter(self, dof)

Stops a degree of freedom from being an external setter.

Parameters

dofDegreeOfFreedom

Dof that is controlling this parameter value

resolve(self)

When this parameters value has some dependency whose value has not yet been set, like during parsing, its value will be a callable object, this method will call this function to return the value.

restore_from_dof(self, bool lock: bool = True, bool verbose: bool = False)

This sets the value of the parameter to what is defined by its external setters, e.g. the value imposed by the degrees of freedom controlling this parameter. Can be used after manually overriding the value of this parameter.

Parameters

lockbool, optional

Locks the parameter after restoring, by default True

verbosebool, optional

Prints the old value, new value and dofs imposing the value, by default False

Raises

FinesseException

When this parameter is not being controlled by any dofs.

set_descendants(self, set descendants) → void

set_dof_setter(self, dof, symbol)

Sets an degree of freedom as an external controller of the value of this parameter.

Parameters

dofDegreeOfFreedom

Element that will be controlling this parameter

symbolsymbolic expression

The expression that this element is imposing upon the parameter.

state

units

unlock(self) → void

Unlock this parameter, allowing its value to be changed. Note this has no effect when actually running a simulation, there parameters will be locked/unlocked depending on which parameters are changing.

unlocked(self)

Context manager for temporarily unlocking this parameter to be allowed to change its value.

value

class finesse.parameter.ParameterRef(param)

Bases: Symbol

A symbolic instance of a parameter in the model.

A parameter is owned by some model element, which can be used to connect its value to other aspects of the simulation.

property cyexpr_name

Name of the parameter reference in cyexpr compatibility format.

This is equivalent to ParameterRef.name but with "." replaced with "_", converted to lower case and encoded in UTF-8 format as a bytes object.

The above format makes this compatible with passing to the underlying math evaluator engine (tinyexpr) used via the cyexpr sub-module.

Note

This should, typically, never need to be used outside of internal usage. It exists primarily to act as the owner for the parameter name strings (avoiding dangling pointers in the expression code).

Getter:

Returns the cyexpr compatible name format of the pref name (read-only).

eval(self, keep_changing_symbols=False, subs=None, keep=None, **kwargs)

property full_name

property name

property owner

property parameter

class finesse.parameter.ParameterState(*values)

Bases: __Pyx_FlexibleEnumBase

NONE = 4

Numeric = 1

Symbolic = 3

Unresolved = 2

class finesse.parameter.PostValidator(post_validate)

Bases: object

class finesse.parameter.Validator(validate)

Bases: object

finesse.parameter.bool_parameter(name, description, units=None, validate=None, post_validate=None, is_default=False, is_geometric=False, changeable_during_simulation=True)

A parameter of an element whose value is decribed by a True or False value.

finesse.parameter.deref(parameter)

Get the Parameter from a ParameterRef or Parameter (no-op).

This is useful in actions which require a parameter but may be passed either a parameter or parameter reference.

finesse.parameter.enum_parameter(name, description, enum, units=None, validate=None, post_validate=None, is_default=False, is_geometric=False, changeable_during_simulation=True)

A parameter of an element whose value is decribed by a Enum definition.

Enum must only use integer values to describe its members. Unlike a general python Enum which can use strings.

finesse.parameter.float_parameter(name, description, units=None, validate=None, post_validate=None, is_default=False, is_geometric=False, changeable_during_simulation=True)

A parameter of an element whose value is decribed by a 64-bit floating point number.

finesse.parameter.info_parameter(name, description, units=None)

Decorator to register an info parameter field in the class.

Info parameters are purely informative properties, and cannot be directly scanned using an axis.

finesse.parameter.int_parameter(name, description, units=None, validate=None, post_validate=None, is_default=False, is_geometric=False, changeable_during_simulation=True)

A parameter of an element whose value is decribed by a 64-bit integer number.

class finesse.parameter.parameterproperty(full_name, doc=None)

Bases: property

Descriptor class for declaring a simulation parameter. A simulation parameter is one that can be changed during a simulation and affect the resulting outputs. The idea is that output dependant variables should be marked as having been changed or will be changed during a simulation run. This allows us to then optimise parts of the model, as we can determine what will or will not be changing. This descriptor is paired with the :class:Parameter.

Parameters can then be superficially locked once a model has been built so accidentally changing some parameter that isn’t expected to change can flag a warning.

getter(self, fget)

setter(self, fset)