Source code for finesse.components.general

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

from copy import copy
from collections import OrderedDict
import enum
import logging
import numbers

import numpy as np

from finesse.components.node import NodeType, Port
from finesse.exceptions import ComponentNotConnected, NoCouplingError
from finesse.utilities import check_name, is_iterable
from finesse.element import ModelElement
from finesse.utilities.misc import DeprecationHelper


LOGGER = logging.getLogger(__name__)


# IMPORTANT: renaming this class impacts the katscript spec and should be avoided!
[docs]class Variable(ModelElement): """The variable element acts slightly different to other elements. When added to a model it creates a new :class:`finesse.parameter.Parameter` in the model it has been added to. This does the same as calling :function:`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 :function:`finesse.model.Model.add_parameter` for more details. """ def __init__( self, name: str, value, description: str = None, units: str = "", is_geometric: bool = False, changeable_during_simulation: bool = True, ): super().__init__(name) self.value = value self.description = description self.units = units self.is_geometric = is_geometric self.changeable_during_simulation = changeable_during_simulation
[docs]class LocalDegreeOfFreedom: """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 ---------- name : str 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 DC : Parameter, optional The DC equivlent of the AC signal node of an element, setting to `None` means no DC actuation happens. AC_IN : SignalNode The node that is driven for this degree of freedom, cannot be None. DC_2_AC_scaling : float, optional Scaling factor relating the DC and AC parameter and nodes. For example, the scaling between phi (degrees) and `mirror.mech.z` (meters). AC_OUT : SignalNode, optional The node that is read out to describe this degree of freedom, if `None` there is nothing to readout here. """ def __init__(self, name, DC=None, AC_IN=None, DC_2_AC_scaling=None, AC_OUT=None): self.name = name self.DC = DC self.AC_IN = AC_IN self.DC_2_AC_scaling = DC_2_AC_scaling if AC_OUT is None: self.AC_OUT = AC_IN else: self.AC_OUT = AC_OUT # if self.AC_IN.type != self.AC_OUT.type: # raise FinesseException( # f"Nodes {self.AC_IN} and {self.AC_OUT} must be of the same type: {self.AC_IN.type}!={self.AC_OUT.type}" # ) @property def AC_IN_type(self): if self.AC_IN: return self.AC_IN.type else: return None @property def AC_OUT_type(self): if self.AC_OUT: return self.AC_OUT.type else: return None def __repr__(self): return f"<'{self.name}' @ {hex(id(self))} ({self.__class__.__name__}) DC={self.DC} AC_IN={self.AC_IN} AC_OUT={self.AC_OUT}>"
DOFDefinition = DeprecationHelper( "DOFDefinition", "finesse.components.general.LocalDegreeOfFreedom", LocalDegreeOfFreedom, "3.b0", )
[docs]def 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. """ def func(cls): cls._unique_element = True return cls return func
[docs]def borrows_nodes(): """Flags that a ModelElement will be making references to nodes owner by other elements, or borrows a reference.""" def func(cls): cls._borrows_nodes = True return cls return func
[docs]@enum.unique class CouplingType(enum.Enum): """An enum describing the type of coupling between two nodes.""" OPTICAL_TO_OPTICAL = 0 OPTICAL_TO_ELECTRICAL = 1 OPTICAL_TO_MECHANICAL = 2 ELECTRICAL_TO_ELECTRICAL = 3 ELECTRICAL_TO_OPTICAL = 4 ELETRICAL_TO_MECHANICAL = 5 MECHANICAL_TO_MECHANICAL = 6 MECHANICAL_TO_OPTICAL = 7 MECHANICAL_TO_ELECTRICAL = 8
[docs]@enum.unique class NoiseType(enum.Enum): """An enum describing the type of noise a component generates.""" QUANTUM = 0
[docs]def determine_coupling_type(from_node, to_node): """Retrieves the type of coupling (see :class:`.CouplingType`) between two nodes. Parameters ---------- from_node : :class:`.Node` Node which couples into `to_node`. to_node : :class:`.Node` Node which has a coupling from `from_node`. Returns ------- coupling_t : :class:`.CouplingType` The type of coupling between the two given nodes. """ convert = { (NodeType.OPTICAL, NodeType.OPTICAL): CouplingType.OPTICAL_TO_OPTICAL, (NodeType.OPTICAL, NodeType.ELECTRICAL): CouplingType.OPTICAL_TO_ELECTRICAL, (NodeType.OPTICAL, NodeType.MECHANICAL): CouplingType.OPTICAL_TO_MECHANICAL, ( NodeType.ELECTRICAL, NodeType.ELECTRICAL, ): CouplingType.ELECTRICAL_TO_ELECTRICAL, (NodeType.ELECTRICAL, NodeType.OPTICAL): CouplingType.ELECTRICAL_TO_OPTICAL, ( NodeType.ELECTRICAL, NodeType.MECHANICAL, ): CouplingType.ELETRICAL_TO_MECHANICAL, ( NodeType.MECHANICAL, NodeType.MECHANICAL, ): CouplingType.MECHANICAL_TO_MECHANICAL, (NodeType.MECHANICAL, NodeType.OPTICAL): CouplingType.MECHANICAL_TO_OPTICAL, ( NodeType.MECHANICAL, NodeType.ELECTRICAL, ): CouplingType.MECHANICAL_TO_ELECTRICAL, } return convert[(from_node.type, to_node.type)]
[docs]@enum.unique class InteractionType(enum.Enum): """An enum describing the type of interaction between two nodes.""" REFLECTION = 0 TRANSMISSION = 1
[docs]class FrequencyGenerator: """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. """ def _couples_frequency(self, ws, connection, frequency_in, frequency_out): """This method returns whether this element is coupling frequencies for a particular connection. For example, a modulator would modulator frequencies when a field passes through it. Or a suspended mirror would couple the upper and lower sidebands on reflection due to radiation pressure effects. Parameters ---------- ws : :class:`.ElementWorkspace` Workspace for this particular component connection : str Name of the connection being queried frequency_in : :class:`.Frequency` Input frequency frequency_out : :class:`.Frequency` Output frequency Returns ------- bool True if frequencies couple at this element """ return False def _modulation_frequencies(self): return [] def _source_frequencies(self): return [] def _on_response(self, freqWeakRef): """Callback function that model calls to say whether requested frequency was granted or not. If so a weak reference to the frequency object is returned. Parameters ---------- freqWeakRef: Weakref.ref Weak reference to the assigned Frequency object Raises ------ Exception If passed a name to a frequency this element did not ask for originally. """ # if freqWeakRef() in self.__requested_frequencies: self.__frequencies.append(freqWeakRef)
# else: # raise Exception(f"{self} never requested a frequency {freqWeakRef()}")
[docs]class NoiseGenerator: """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. """ def __init__(self): self.__noises = {} def _register_noise_output( self, name, node, noise_type, ): if noise_type not in self.__noises.keys(): self.__noises[noise_type] = [] self.__noises[noise_type].append((name, node)) def _couples_noise(self, ws, node, noise_type, frequency_in, frequency_out): """This method returns whether the noise sidebands this element produces are covariant for the specified frequencies at this node. Parameters ---------- ws : :class:`.ElementWorkspace` Workspace for this particular component node : :class:`.Node` Node to check. noise_type : :class:`.NoiseType` NoiseType to check. frequency_in : :class:`.Frequency` Input frequency frequency_out : :class:`.Frequency` Output frequency Returns ------- bool True if the specified sidebands are covariant. """ return frequency_in.index == frequency_out.index @property def noises(self): return self.__noises
# IMPORTANT: renaming this class impacts the katscript spec and should be avoided!
[docs]class Connector(ModelElement): """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 ---------- name : str Name of the new `Connector` instance. """ _borrows_nodes = False
[docs] def __init__(self, name): super().__init__(name) self.__connections = OrderedDict() self.__enabled_checks = OrderedDict() self.__ports = OrderedDict() self.__interaction_types = {} self.__nodes = OrderedDict() self._abcd_matrices = {} self.__abcds_symbolised = False
def __nodes_of(self, *node_types): return tuple([node for node in self.nodes.values() if node.type in node_types]) @property def borrows_nodes(self): """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. """ return self._borrows_nodes @property def optical_nodes(self): """The optical nodes stored by the connector. :`getter`: Returns a list of the stored optical nodes (read-only). """ return self.__nodes_of(NodeType.OPTICAL) @property def signal_nodes(self): """The signal nodes stored by the connector. :`getter`: Returns a list of the stored signal nodes (read-only). """ return self.__nodes_of(NodeType.ELECTRICAL, NodeType.MECHANICAL) @property def ports(self): """Retrieves the ports available at the object. Returns ------- tuple Read-only tuple of the ports available at this object. """ return tuple(self.__ports.values()) def _add_port(self, name, type): """Creates either an electrical, mechanical, or optical port for this component. Each port can then have multiple different nodes associated with - each node being an equation to solve for in the linear system. For example, the input and output optical field at one part of a component would be one port, i.e. reflection from one side of a mirror. The port is added to the component object directly to be referenced at a later time when the users is connecting components or definining couplings in a component. Parameters ---------- name : str Name of the port type : NodeType Type of nodes this port holds Returns ------- Port object added """ check_name(name) if name in self.ports: raise Exception("Port %s already exists for this object" % name) if hasattr(self, name): raise Exception( "Port name %s already exists as an attribute in of this object" % name ) p = Port(name, self, type) self.__ports[name] = p # self._unfreeze() assert not hasattr(self, name) setattr(self, name, p) # self._freeze() return p @property def _enabled_checks(self): return copy(self.__enabled_checks) @property def _registered_connections(self): return copy(self.__connections) @property def all_internal_optical_connections(self): """A dictionary of all the optical connections this element is making between its nodes.""" return { k: (self.nodes[v[0]], self.nodes[v[1]]) for k, v in self.__connections.items() if ( self.coupling_type(self.nodes[v[0]], self.nodes[v[1]]) == CouplingType.OPTICAL_TO_OPTICAL ) } @property def all_internal_connections(self): """A dictionary of all the connections this element is making between its nodes.""" return { k: (self.nodes[v[0]], self.nodes[v[1]]) for k, v in self.__connections.items() }
[docs] def coupling_type(self, from_node, to_node): """Obtains the type of coupling (see :class:`.CouplingType`) between the two specified nodes at this component. Parameters ---------- from_node : :class:`.Node` Node which has a forwards coupling to `to_node`. to_node : :class:`.Node` Node which has a backwards coupling from `from_node`. Returns ------- coupling_t : :class:`.CouplingType` The type of coupling between the specified nodes. """ try: return determine_coupling_type(from_node, to_node) except KeyError: return None
[docs] def interaction_type(self, from_node, to_node): """Obtains the type of interaction (see :class:`.InteractionType`) between the two specified nodes at this component. Parameters ---------- from_node : :class:`.Node` Node which has a forwards coupling to `to_node`. to_node : :class:`.Node` Node which has a backwards coupling from `from_node`. Returns ------- interaction_t : :class:`.InteractionType` The type of interaction between the specified nodes. """ try: if hasattr(from_node, "full_name"): from_node = from_node.full_name if hasattr(to_node, "full_name"): to_node = to_node.full_name return self.__interaction_types[(from_node, to_node)] except KeyError: return None
@property def nodes(self): """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 ------- nodes : tuple(:class:`.Node`) Copy of nodes dictionary """ return copy(self.__nodes) def _register_node_coupling( self, connection_id: str, from_node, to_node, interaction_type=None, forced_name=None, enabled_check=None, ): """Registers that this element will connect the output of one of its nodes to the input of another. Each element is responsible for requesting connections to be made within a Model. In practice this means the model will allocate the required matrix elements for this element to fill in. Parameters ---------- connection_id : str A unique string ID for this element which is used to identify this connection. from_node : :class:`.Node` The input node to_node : :class:`.Node` The output node interaction_type : :class:`.InteractionType`, optional The type of interaction between the nodes if applicable. forced_name : str, optional Can force the name of a connection. Used by spaces/wires for using the correct name as it doesn't own the node enabled_check : function, optional A function that returns a True/False if this connection should be enabled when a simulation is built from a model. The default value None means True. """ from finesse.components import Space, Wire if forced_name is None: name = "{}->{}".format(from_node.full_name, to_node.full_name) else: name = forced_name try: if self._model is not None: raise Exception("Component has already been added to a model") except ComponentNotConnected: pass if name in self.__connections: raise Exception( "Connection called {} already set at component {}".format( self.name, name ) ) # TODO: decide whether we actually need this - shouldn't be possible # to connect non-existing ports without python complaining about # an undefined parameter first anyway if isinstance(self, Space) or isinstance(self, Wire): if from_node.port not in from_node.port.component.ports: raise Exception() if to_node.port not in to_node.port.component.ports: raise Exception() else: if from_node.full_name not in self.nodes: raise Exception( "Node {}.{} is not available at component `{}`".format( from_node.port.name, from_node.name, self.name ) ) if to_node.full_name not in self.nodes: raise Exception( "Node {}.{} is not available at component `{}`".format( to_node.port.name, to_node.name, self.name ) ) if (from_node.full_name, to_node.full_name) in self.__connections.values(): raise Exception( f"Connection between {(from_node.full_name, to_node.full_name)} already exists" ) self.__connections[connection_id] = (from_node.full_name, to_node.full_name) if enabled_check: self.__enabled_checks[connection_id] = enabled_check if interaction_type is not None: self.__interaction_types[(from_node.full_name, to_node.full_name)] = ( interaction_type )
[docs] def is_valid_coupling(self, from_node, to_node): """Flags whether the provided node coupling exists at this connector.""" return (from_node.full_name, to_node.full_name) in self.__connections.values()
[docs] def check_coupling(self, from_node, to_node): """Checks that a coupling exists between `from_node` -> `to_node` and raises a ``ValueError`` if not.""" fname, tname = from_node.full_name, to_node.full_name if (fname, tname) not in self.__connections.values(): raise NoCouplingError(f"No coupling exists between {fname} -> {tname}")
def _parse_from_to_nodes(self, from_node, to_node): if isinstance(from_node, numbers.Integral): from_node = getattr(self, f"p{from_node}") if isinstance(to_node, numbers.Integral): to_node = getattr(self, f"p{to_node}") if isinstance(from_node, Port): from_node = from_node.i if isinstance(to_node, Port): to_node = to_node.o return from_node, to_node def _resymbolise_ABCDs(self): # By default components will not have to resymbolise optical ABCD matrices pass
[docs] def register_abcd_matrix(self, 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_sym : :class:`numpy.ndarray` A 2x2 matrix of symbolic elements describing the analytic form of the ABCD matrix for the given coupling(s). couplings : sequence 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. """ M_num = np.array(M_sym, dtype=np.float64) for coupling in couplings: if not is_iterable(coupling) or len(coupling) < 2 or len(coupling) > 3: raise ValueError( f"Expected coupling {coupling} passed to _register_abcd_matrix " "to be an iterable of length two (from_node, to_node) or " "length three (from_node, to_node, direction)." ) # No plane given, so same matrix will be used for # both planes at this given node coupling if len(coupling) == 2: from_node, to_node = coupling direction = ("x", "y") # Otherwise use the specified plane else: from_node, to_node, direction = coupling if direction != "x" and direction != "y": raise ValueError( f"Expected direction argument of coupling {coupling} to " f"be either 'x' or 'y' but got {direction}." ) direction = (direction,) # Check that the node coupling actually exists on this connector self.check_coupling(from_node, to_node) for d in direction: key = (from_node, to_node, d) if key in self._abcd_matrices: raise ValueError( f"There is already an ABCD matrix defined for the coupling " f"{from_node.full_name} -> {to_node.full_name} in the " f"plane '{d}'!" ) LOGGER.debug( "For node coupling %s -> %s, in plane %s, registered " "ABCD matrix:\n Symbolic: %s, Current Numeric: %s", from_node.full_name, to_node.full_name, d, M_sym.tolist(), M_num.tolist(), ) self._abcd_matrices[(from_node, to_node, d)] = M_sym, M_num
def _re_eval_abcds(self): for M_sym, M_num in self._abcd_matrices.values(): M_num[:] = np.array(M_sym, dtype=np.float64)
[docs] def ABCD( self, from_node, to_node, direction="x", symbolic=False, copy=True, retboth=False, allow_reverse=False, ): """ Parameters ---------- from_node : :class:`.OpticalNode` or :class:`.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_node : :class:`.OpticalNode` or :class:`.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. direction : str, optional; default: 'x' Direction of ABCD matrix computation, default is 'x' for tangential plane. symbolic : bool, optional; default: False Whether to return the symbolic matrix (as given by equations above). Defaults to False such that the numeric matrix is returned. copy : bool, 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. retboth : bool, optional; default: False Whether to return both the symbolic and numeric matrices as a tuple in that order. allow_reverse : bool, 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 ------- M : :class:`numpy.ndarray` The ABCD matrix of the specified coupling for the mirror. This is symbolic if either of `symbolic` or `retboth` flags are True. M2 : :class:`numpy.ndarray` Only returned if `retboth` is True, otherwise just `M` above is returned. This will always be the numeric matrix. Raises ------ err : :class:`ValueError` If no coupling exists between `from_node` and `to_node`. """ from_node, to_node = self._parse_from_to_nodes(from_node, to_node) try: self.check_coupling(from_node, to_node) except NoCouplingError: if allow_reverse: self.check_coupling(to_node.opposite, from_node.opposite) else: raise if not self.__abcds_symbolised: self._resymbolise_ABCDs() self.__abcds_symbolised = True key = (from_node, to_node, direction) if key not in self._abcd_matrices: # If an optical coupling exists and no abcd has been specfied # then we can assume it is an identity transformation M_sym = np.eye(2, dtype=object) M_num = np.eye(2) else: M_sym, M_num = self._abcd_matrices[key] if M_sym is None: # Symbolic M is None if an error occurred during the tracing # In such a case M_num is a TotalReflectionError or # some other exception instance raise M_num # Evaluate M_sym and assign to memory of M_num so that # M_num always corresponds to current parameter state M_num[:] = np.array(M_sym, dtype=np.float64) if copy: Ms = M_sym.copy() Mn = M_num.copy() else: Ms = M_sym Mn = M_num if retboth: return Ms, Mn if symbolic: return Ms return Mn