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

add_dependency(self, param)

Declare an additional dependency of this parameter on param.

The dependency is used like a symbolic link: when the value of param changes, the post-validator of this parameter is called and its change count is incremented. It will also be included in the dependencies graph to determine which parameters are changing.

The caller of this function is responsible for implementing the actual numerical connection between the two parameters.

The dependency may be declared before this parameter is connected to a model: only the full name is stored and it is resolved against the model when the descendants are updated.

Parameters

paramParameter | ParameterRef | str

The parameter this parameter depends on, or its full name, like l1.P.

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

get_descendants(self) → set

All parameters that depend on this parameter, directly or through a chain of dependencies, as maintained by Model.update_parameter_descendants().

Returns

set of Parameter

A copy of the descendants of this parameter.

get_direct_dependencies(self) → set

The full names of the parameters this parameter directly depends on.

This is the set of the full names of the parameters referenced by this parameter’s symbolic value, if any, plus the dependencies declared with add_dependency(). The names are not resolved against the model: that happens in Model.update_parameter_descendants().

Returns

set of str

The full names of the parameters this parameter directly depends on.

is_changing

Parameter.is_changing: bool

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_reference

Parameter.is_reference: bool

True if this parameter if a ParameterRef

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.

parameter

So a ParameterRef and Parameter can both call .parameter to get a Parameter

ref

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

remove_dependency(self, param)

Remove an additional dependency previously registered with add_dependency().

Parameters

paramParameter | ParameterRef | str

The parameter to remove from this parameter’s dependencies, or its full name.

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

This function is called by Model and should not be called directly. The values will be overwritten when the model update.

To add dependencies use Parameter.add_dependency().

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.

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

property full_name

ParameterRef.is_reference -> bool

True if this parameter if a ParameterRef

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)