class finesse.model.Model(maxtem=None, selected_modes=None)[source]

Optical configuration class for handling models of interferometers.

This class stores the interferometer configuration as a directed graph and contains methods to interface with this data structure.


maxtem : int, optional

The maximum transverse electromagnetic mode order, defaults to None indicating a plane wave model. If this value is specified, then the model will automatically be switched to a modal basis.

selected_modes : sequence or str, optional

Specific HOMs to select for modelling. Can be given as a sequence of strings (e.g: ["00", "21"] to select the TEM00 and TEM21 modes), or a sequence of two-element tuples (e.g: [(0,0), (1, 3)] to select the TEM00 and TEM13 modes).

OR a string identifier for the type of modes to include. This can be one of “even”, “odd”, “tangential”, “sagittal”, “x” or “y”.


If both maxtem and selected_modes are None then the model will represent a plane-wave model, otherwise it will be a modal model. Note that this can be altered after construction via Model.maxtem or Model.select_modes().



Dictionary of all the model elements with the keys as their names

The directed graph object containing the optical configuration as a networkx.DiGraph instance.


A copy of the directed graph object stored by but only containing nodes of type OpticalNode and only with edges that have couplings to optical nodes.


The optical nodes stored in the model.


The mechanical nodes stored in the model.


The electrical nodes stored in the model.


A dictionary of optical nodes that have beam parameters set manually - stores the nodes themselves as keys and the corresponding beam parameters as values.


The default frequency to use for the model.


The spatial type of the model - i.e.


Flag indicating whether the model is modal or plane-wave.


An ordered dictionary where the key type is the modes in the model and the mapped type is the index of the mode.


Number of higher-order modes (HOMs) included in the model.


The frequencies stored in the model as a list instance.


The source frequencies stored in the model as a Dictionary instance, with frequencies as keys, and a list of components that depend on a given frequency as values.


The components stored in the model as a tuple object.


The detectors stored in the model as a tuple object.


The cavities stored in the model as a tuple object.



Flag indicating whether the model has been built.


The arguments to be passed to calls to Model.beam_trace() during a simulation.


An instance of SimulationTraceSolution containing the output of the most recent beam trace performed on the model.


When the model has been built this property returns the carrier simulation


When the model has been built this property returns the signal simulation


Model.__init__(self[, maxtem, selected_modes])

Initialize self.



Generate an undirected graph containing components as the nodes of the graph and connections (spaces, wires, joints) between component nodes as the edges of the graph.


The default wavelength to use for the model.


Scaling factor for mechanical motion to optical modulation.


An array of higher-order modes (HOMs) included in the model.


The maximum Tranverse Electro-magnetic Mode (TEM) order associated with the model.

Model.include_modes(self, modes)

Inserts the mode indices in modes into the Model.homs array at the correct (sorted) position(s).

Model.select_modes(self, select[, maxtem])

Select the HOM indices to include in the model.

Model.add_all_ad(self, node[, f])

Adds amplitude detectors at the specified node and frequency f for all Higher Order Modes in the model.


An integer corresponding to the phase level given to the phase command of a Finesse 2 kat script.

Model.force_retrace(self[, all_points])

Force a beam retrace of the model on the next call (internal or otherwise) to Model.beam_trace().


Switch off retracing of the beam.

Model.tag_node(self, node, tag)

Tag a node with a unique name.

Model.remove(self, obj)

Removes an object from the model.

Model.reduce_get_attr(self, attr)

Model.add(self, obj)

Adds an element (or sequence of elements) to the model - these can be ModelElement sub-class instances.

Model.parse(self, text)

Parses kat script and adds the resulting objects to the model.

Model.parse_file(self, path)

Parses kat script from a file and adds the resulting objects to the model.

Model.parse_legacy(self, text)

Parses legacy (Finesse 2) kat script and adds the resulting objects to the model.

Model.parse_legacy_file(self, path)

Parses legacy (Finesse 2) kat script from a file and adds the resulting objects to the model.

Model.merge(self, other, from_comp, …[, …])

Merges the model other with this model using a connection at the specified ports.

Model.add_frequency(self, freq)

Add a SourceFrequency to the model description.

Model.get_frequency_object(self, frequency_value)

Model.chain(self, \*args[, start, port])

Utility function for connecting multiple connectable objects in a sequential list together.

Model.connect(self, A, B[, name, L, nr, …])

Connects two ports in a model together.


Plots the configuration with nodes positioned using the Fruchterman-Reingold force-directed algorithm.




If a model has been built then this function undoes the process so the model can be changed and rebuilt if required.

Runs the current analysis set for this model.


Model.path(self, from_node, to_node[, via_node])

Retrieves an ordered container of the path trace between the specified nodes.

Model.sub_model(self, from_node, to_node)

Obtains a subgraph of the complete configuration graph between the two specified nodes.

Model.component_tree(self, root)

Retrieves a tree containing the network representing the components connected to the specified root.

Model.detect_mismatches(self[, use_last_trace])

Detect mismatches at each surface of the model.

Model.print_mismatches(self[, table_fmt])

Prints the mismatches computed by Model.detect_mismatches() to an easily readable table.

Model.create_mismatch(self, node[, w0_mm, z_mm])

Sets the beam parameters such that a mismatch of the specified percentage magnitude (in terms of \(w_0\) and \(z\)) exists at the given node.

Model.update_gauss(self, node[, qx, qy])

Model.ABCD(self[, from_node, to_node, …])

Computes the combined ABCD matrix through a given path.

Model.beam_trace(self[, startnode, order, …])

Performs a beam trace setting/updating entries for all optical nodes in the Model.last_trace dictionary.

Model.utility_trace(self, q_in[, from_node, …])

Traces a beam of arbitrary geometry (specified with q_in) through a given path.