finesse.parameter module
- class finesse.parameter.EnumCaster(enum, validate)[source]
Bases:
objectEnums 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)[source]
Bases:
ParameterSpecialised 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.
- class finesse.parameter.Parameter(parameter_info, owner)[source]
Bases:
object- add_dependency(self, param)[source]
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
- check_dof_setters(self) tuple[bool, Symbol | float][source]
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: the part of the value saved when a link first broke plus every setter’s term
- datatype_cast(self, value, ignore_failure=False)[source]
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[source]
Check whether this parameter symbolically depends on another parameter
- eval(self, bool keep_changing_symbols=False)[source]
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.
- 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.
- set of
- 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 inModel.update_parameter_descendants().Returns
- set of str
The full names of the parameters this parameter directly depends on.
- is_changing[source]
Parameter.is_changing: bool
True if this parameter will be changing during a simulation.
- is_controlled_by_dof[source]
Whether the link to any degree of freedom controlling this parameter is intact.
- is_geometric
- is_nr
- lambdify(self, *args)[source]
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, *, bool exclusive=True)[source]
Lock this parameter, preventing it’s value from being updated until you call
unlock. Locks persist through simulations, so a locked parameter cannot be scanned either. During a simulation the model also locks every parameter that is not changing, and removes only that lock afterwards.Locking again with the same owner only updates whether its lock is exclusive.
Parameters
- bystr
Name of the owner of the lock.
- exclusivebool, optional
An exclusive lock claims this parameter for its owner alone. A non-exclusive lock is held by one of possibly several drivers whose contributions add up, such as DegreeOfFreedom. Defaults to True.
- lock_toggled_by[source]
Parameter.lock_toggled_by: list[str]
Names of the object that toggled the lock on this parameter
- owner[source]
The component/element this parameter is associated with, this could be a
finesse.element.ModelElementor afinesse.model.Model.
- remove_dependency(self, param)[source]
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.
- resolve(self)[source]
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)[source]
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. The part of the value that is not set by the degrees of freedom is kept.
Parameters
- lockbool, optional
Locks the parameter as each degree of freedom controlling it 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.
- ParameterLocked
When the value needs restoring and an owner holds an exclusive lock.
- 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().
- state
- unlock(self, str by=None) void
Unlock this parameter, allowing its value to be changed. During a simulation the model still locks every parameter that is not changing, and removes only that lock afterwards.
Parameters
- bystr, optional
Only remove the lock held by this owner, if any. The parameter stays locked while other owners hold locks. Defaults to None which removes every lock.
- class finesse.parameter.ParameterRef(param)[source]
Bases:
SymbolA 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.
- ParameterRef.is_reference -> bool
True if this parameter if a ParameterRef
- finesse.parameter.bool_parameter(name, description, units=None, validate=None, post_validate=None, is_default=False, is_geometric=False, changeable_during_simulation=True)[source]
A parameter of an element whose value is decribed by a True or False value.
- finesse.parameter.deref(parameter)[source]
Get the
Parameterfrom aParameterReforParameter(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)[source]
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)[source]
A parameter of an element whose value is decribed by a 64-bit floating point number.
- finesse.parameter.info_parameter(name, description, units=None)[source]
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)[source]
A parameter of an element whose value is decribed by a 64-bit integer number.
- class finesse.parameter.parameterproperty(full_name, doc=None)[source]
Bases:
propertyDescriptor 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.