finesse.components.general module

Top-level objects which specific optical, and otherwise, components should inherit from.

class finesse.components.general.Connector(*args, **kwargs)

Bases: ModelElement, ABC

Base class for any component which connects nodes together.

Internally it stores the nodes and the connections associated with the component. During the matrix build this class will then ensure that the matrix elements for each coupling requested are allocated and and the required matrix view for editing their values is retrieved.

The inheriting class should call _register_node and _register_coupling to define the connections it wants to use.

Parameters

namestr

Name of the new Connector instance.

ABCD(from_node, to_node, direction='x', symbolic=False, copy=True, retboth=False, allow_reverse=False)

Parameters

from_nodeOpticalNode or Port or str or int

Input node. If a port, or string repr of a port, is given then the input optical node of that port will be used.

to_nodeOpticalNode or Port or str or int

Output node. If a port, or string repr of a port, is given then the output optical node of that port will be used.

directionstr, optional; default: ‘x’

Direction of ABCD matrix computation, default is ‘x’ for tangential plane.

symbolicbool, optional; default: False

Whether to return the symbolic matrix (as given by equations above). Defaults to False such that the numeric matrix is returned.

copybool, optional; default: True

Whether to return a copy of ABCD matrix (or matrices if retboth is true). Defaults to True so that the internal matrix cannot be accidentally altered. Use caution if switching this flag off.

retbothbool, optional; default: False

Whether to return both the symbolic and numeric matrices as a tuple in that order.

allow_reversebool, optional

When True, if the coupling does not exist at the component from_node->to_node but to_node->from_node does exist, it will return the ABCD from that. Otherwise a NoCouplingError will be raised.

Returns

Mnumpy.ndarray

The ABCD matrix of the specified coupling for the mirror. This is symbolic if either of symbolic or retboth flags are True.

M2numpy.ndarray

Only returned if retboth is True, otherwise just M above is returned. This will always be the numeric matrix.

Raises

finesse.exceptions.NoCouplingError

If no coupling exists between from_node and to_node.

finesse.exceptions.NoABCDCoupling

If no ABCD matrix has been defined for the requested coupling.

finesse.exceptions.TotalReflectionError

Total reflection of a beam at a component when performing beam tracing.

property all_internal_connections

A dictionary of all the connections this element is making between its nodes.

property all_internal_optical_connections

A dictionary of all the optical connections this element is making between its nodes.

property borrows_nodes

Whether this element borrows node references from another.

When this is True the element may not create all of its own nodes and just link into one that already exists and is owned by another element.

check_coupling(from_node, to_node)

Checks that a coupling exists between from_node -> to_node and raises a ValueError if not.

coupling_overview(add_enabled: bool = False) → Table

Overview of the couplings between the different nodes of this connector. Shows the input and output node, the unit of the coupling (as a reference for transfer functions) and the type of coupling.

Parameters

add_enabledbool, optional

Adds a column that shows whether a coupling is enabled. Only relevant for suspended optics, by default False

Returns

Table

Overview table.

coupling_type(from_node, to_node) → CouplingType

Obtains the type of coupling (see CouplingType) between the two specified nodes at this component.

Parameters

from_nodeNode

Node which has a forwards coupling to to_node.

to_nodeNode

Node which has a backwards coupling from from_node.

Returns

coupling_tCouplingType

The type of coupling between the specified nodes.

property electrical_ports: tuple[Port, ...]

Retrieves the electrical ports available at the object.

Returns

tuple

Read-only tuple of the ports available at this object.

interaction_type(from_node, to_node)

Obtains the type of interaction (see InteractionType) between the two specified nodes at this component.

Parameters

from_nodeNode

Node which has a forwards coupling to to_node.

to_nodeNode

Node which has a backwards coupling from from_node.

Returns

interaction_tInteractionType

The type of interaction between the specified nodes.

is_valid_coupling(from_node, to_node)

Flags whether the provided node coupling exists at this connector.

property mechanical_ports: tuple[Port, ...]

Retrieves the mechanical ports available at the object.

Returns

tuple

Read-only tuple of the ports available at this object.

node_overview() → Table

Overview of the nodes in this connector, showing their type and unit.

Returns

Table

Overview table

property nodes

All the nodes of all the ports at this component. Order is likely to be the order in which the ports and nodes were created, but this is not guaranteed.

Returns

nodestuple(Node)

Copy of nodes dictionary

property optical_nodes

The optical nodes stored by the connector.

Getter:

Returns a list of the stored optical nodes (read-only).

property optical_ports: tuple[Port, ...]

Retrieves the optical ports available at the object.

Returns

tuple

Read-only tuple of the optical ports available at this object.

port_overview() → Table

Get an overview of the ports in this connector, showing their type and the nodes they contain

Returns

Table

Overview table

property ports: tuple[Port, ...]

Retrieves the ports available at the object.

Returns

tuple

Read-only tuple of the ports available at this object.

register_abcd_matrix(M_sym, *couplings)

Register an ABCD matrix of the given symbolic form for a sequence of coupling(s).

Specifying several couplings for one M_sym means that all these node couplings will point to the same reference ABCDs — i.e. the matrices kept in the underlying ABCD matrix store will be the same blocks of memory.

Warning

This should only be used in the _resymbolise_ABCDs method of Connectors, when implementing a new component.

Parameters

M_symnumpy.ndarray

A 2x2 matrix of symbolic elements describing the analytic form of the ABCD matrix for the given coupling(s).

couplingssequence of tuples

Arguments of tuples giving the node couplings which are described by the given symbolic ABCD matrix M_sym.

These tuples can be of size two or three, with the first two elements always as the from_node -> to_node instances. The former case implies that both the tangential and sagittal plane ABCD matrix couplings are equal and so both directions ‘x’ and ‘y’ in the underlying matrices store will be set to the same values. Whilst the latter case, where the third element is either ‘x’ or ‘y’, sets just these direction keys to this matrix.

replace(sub: str, component: str | None = None, optical_ports: None | list[str] = None, mechanical_ports: None | list[str] = None, electrical_ports: None | list[str] = None, verbose: bool = False) → str

Unparse the model of this Connector and replace the Connector with a new section of katscript. Returns the katscript for the model with component replaced.

Parameters

substr

New section of katscript that will replace the katscript line defining the component to replace.

componentstr | None, optional

Replacement string for any references of the component name, by default None

optical_portsNone | list[str], optional

Replacement ports for any references of the component optical ports, by default None

mechanical_portsNone | list[str], optional

Replacement ports for any references of the component mechanical ports, by default None

electrical_portsNone | list[str], optional

Replacement ports for any references of the component electrical ports, by default None

verbosebool, optional

Whether to print a diff between the current and new KatScript,

by default False

Returns

str

KatScript with the component replaced.

Raises

FinesseException

When the component to replace is not of type Connector.

property signal_nodes

The signal nodes stored by the connector.

Getter:

Returns a list of the stored signal nodes (read-only).

class finesse.components.general.CouplingType(*values)

Bases: Enum

An enum describing the type of coupling between two nodes.

ELECTRICAL_TO_ELECTRICAL = 3

ELECTRICAL_TO_OPTICAL = 4

ELETRICAL_TO_MECHANICAL = 5

MECHANICAL_TO_ELECTRICAL = 8

MECHANICAL_TO_MECHANICAL = 6

MECHANICAL_TO_OPTICAL = 7

OPTICAL_TO_ELECTRICAL = 1

OPTICAL_TO_MECHANICAL = 2

OPTICAL_TO_OPTICAL = 0

class finesse.components.general.DOFDefinition(*args, **kwargs)

Bases: LocalDegreeOfFreedom

class finesse.components.general.FrequencyGenerator

Bases: object

The base class for components which generate optical frequencies.

A component inheriting from this class will allow the model to query the component to ask what frequencies it wants to use. Frequency generation comes in the form of either a laser or something that modulates.

class finesse.components.general.InteractionType(*values)

Bases: Enum

An enum describing the type of interaction between two nodes.

REFLECTION = 0

TRANSMISSION = 1

class finesse.components.general.LocalDegreeOfFreedom(name: str, DC: Parameter | None = None, AC_IN: Node | None = None, DC_2_AC_scaling: float | None = None, AC_OUT: Node | None = None)

Bases: object

A local degree of freedom definition that combines a DC parameter and AC nodes at some element. For example, this can pair a mirror tuning and it the AC mechanical nodes into one “Degree of Freedom” that can be referenced to scan, drive, or readout. Some DOFs do not have a DC equivalent so the DC part may be None. A DOF can have a different input (drive) and output (readout) signal node. This is used in more advanced cases such as suspension systems, where you drive some motion through a force/torque actuation on some part of the suspension but the readout is in displacement/rotation of the final optic.

Parameters

namestr

Name should be the full-name of the definition for a particular element, e.g. m1.dofs.z if this is wrong, then unparsing will not work correctly

DCParameter, optional

The DC equivlent of the AC signal node of an element, setting to None means no DC actuation happens.

AC_INSignalNode

The node that is driven for this degree of freedom, cannot be None.

DC_2_AC_scalingfloat, optional

Scaling factor relating the DC and AC parameter and nodes. For example, the scaling between phi (degrees) and mirror.mech.z (meters).

AC_OUTSignalNode, optional

The node that is read out to describe this degree of freedom, if None there is nothing to readout here.

property AC_IN_type: NodeType | None

property AC_OUT_type: NodeType | None

class finesse.components.general.MapAndKNMOptic

Bases: object

Shared base class for the finesse.components.lens.Lens and the finesse.components.mirror.Mirror and finesse.components.beamsplitter.Beamsplitter via the finesse.components.surface.Surface parent class. Initializes the finesse.components.general.MapAndKNMOptic.knm_apply_bayer_helms_first with a shared default setting. See How Bayer-Helms and map contributions are combined

knm_apply_bayer_helms_first: bool

class finesse.components.general.MechanicalConnector(*args, **kwargs)

Bases: Connector

property connected_to: Connector

Component that this mechanical element is connected to

property mech_port: Port

Mechanical port that this component is using the nodes from

class finesse.components.general.NoiseGenerator

Bases: object

The base class for components which generate some kind of noise.

A component inheriting from this class will allow the model to query the component to ask what noise it generates.

property noises

class finesse.components.general.NoiseType(*values)

Bases: Enum

An enum describing the type of noise a component generates.

QUANTUM = 0

class finesse.components.general.RelaxingElement(*args, **kwargs)

Bases: ModelElement

A base class for elements that require relaxing during the Relaxation action. A relaxing element should also return a RelaxingWorkspace object when requested by the simulation. The workspace defines the convergence criteria whilst relaxing the parameters returned by relaxing_parameters().

Methods

relaxing_parameters() -> Tuple[Parameter]

Abstract method that must be implemented by subclasses to return the parameters required for relaxation.

relaxing_parameters() → Tuple[Parameter, ...]

class finesse.components.general.TemporalQuasiStaticElement(*args, **kwargs)

Bases: ModelElement

A base class for elements that implements a temporal quasi-static approximation to the behaviour of an element.

This is used in the approximation that some thermal or mechanical effects are slow compared to the proapgation speed of light in the system. This allows the element to use the current simulation state as a static approximation for the inputs to some finite element or other analytic simulation.

temporal_parameters() → Tuple[Parameter, ...]

Returns which parameters will be changed during the simulation.

class finesse.components.general.Variable(*args, **kwargs)

Bases: ModelElement

The variable element acts slightly different to other elements. When added to a model it creates a new finesse.parameter.Parameter in the model it has been added to. This does the same as calling finesse.model.Model.add_parameter(). This new parameter can be used like a variable for making symbolic links to or for storing some useful number about the model.

See finesse.model.Model.add_parameter() for more details.

finesse.components.general.borrows_nodes()

Flags that a ModelElement will be making references to nodes owner by other elements, or borrows a reference.

finesse.components.general.determine_coupling_type(from_node, to_node)

Retrieves the type of coupling (see CouplingType) between two nodes.

Parameters

from_nodeNode

Node which couples into to_node.

to_nodeNode

Node which has a coupling from from_node.

Returns

coupling_tCouplingType

The type of coupling between the two given nodes.

finesse.components.general.unique_element()

Flags that this element type is unique in a model.

In other words, only one of these element types can be in a single model.