finesse.tracing.forest module

The TraceForest data structure used for representing propagating beams in a model.

Details on each class, method and function in this sub-module are provided mostly for developers. Users should refer to Tracing the beam for details on beam tracing, Model.beam_trace() for the main method through which beam traces can be performed on a model and tracing.tools for the various beam propagation tools which the beam tracing library provides.

class finesse.tracing.forest.TraceForest(model, bool symmetric, list trees=None)[source]

Bases: object

A container structure which stores multiple TraceTree instances.

The Model stores a TraceForest object which then represents the current tracing state of the configuration. Each time a Model.beam_trace() is called, either directly or indirectly, the TraceForest of the Model will be used to perform the tracing via propagation of the beam parameters through each tree. This is also detailed in Tracing the beam.

Determination of the ordering and overall structure of the TraceForest happens through the “planting” of the forest. By calling TraceForest.plant(), the forest is cleared and re-planted according to the ordered list of trace dependencies passed to this method. This is a step which is performed automatically in Model.beam_trace(), where this re-planting process only occurs under the following condition:

a connector has been added or removed since the last call,

the type of beam tracing has been switched from symmetric to asymmetric or vice-verase,

or the tracing priority (i.e. ordered list of trace dependencies) has changed in any way.

In the initialisation process of building a simulation, a specialised version of a TraceForest is constructed from the model TraceForest using the TraceForest.make_changing_forest method. This inspects the model forest and selects only those trees, and branches of trees, which will have changing beam parameters during the simulation; i.e. due to some GeometricParameter being scanned. This new, “changing TraceForest” is then the optimised structure via which simulation-time beam traces (on changing beam parameter paths) are performed. More details on this, including additional powerful features that this changing forest provides, can be found in Tracing the beam.

Special method support

This class implements the following special methods: __getitem__, __len__, __iter__, __next__ and __contains__, providing the following behaviour (assuming forest is an instance of this class):

tree = forest[x] - either get the TraceTree at index x (i.e. the x-th tree to be traced when performing a beam trace on the forest), OR if x is a TraceDependency get a list of all the trees in the forest which are associated with that dependency.

N_trees = len(forest) - the number of trees in the forest, equivalent to TraceForest.size().

for tree in forest: - iteration support over the forest, in order of tracing priority.

flag = x in forest - check whether some object x is in the forest. This can be a TraceTree, an OpticalNode, a Space or a Connector. Equivalent to TraceForest.contains().

clear(self) → void: Clears the trace forest, removing all trace trees.

contains(self, o) → bool

Whether the forest contains the specified object, determined recursively for each tree within the forest.

Parameters

o[TraceTree | OpticalNode | Space | Connector]: The object to search for in the forest.

Returns

flagbool: True if o is in the forest, False otherwise.

dependencies

draw(self)[source]

Draws the forest, by trace priority, as a string representation.

The order in which trees appear in this string represents the order in which they will be traced during the beam tracing algorithm.

In the rare cases where a subsequent tree contains a duplicate node (from an earlier tree), the latter tree trace will overwrite the former. This is only applicable to configurations with overlapping cavities, and this overwriting behaviour will take account of the desired cavity ordering given by the user.

Returns

forest_strstr: A string representation of the ordered forest.

draw_by_dependency(self)[source]

Draws the forest as a string representation.

All the trees in the forest are sorted by their dependency and stored in the resultant string by these dependency sub-headings. Each tree also has its index (i.e. tracing priority) stored in the string above the drawn tree.

Returns

forest_strstr: A string representation of the forest, sorted by dependency with tracing priority indices displayed for each tree.

empty(self) → bool: Whether the forest is empty (no trees) or not.

external_cavity_trees[source]

find_dependency_from_node(self, node, bool raise_not_found=True)

Finds the dependency object associated with the optical node.

If no tree is found associated with this node, and raise_not_found is true, then a BeamTraceException is raised. Otherwise None is returned.

Parameters

nodeOpticalNode: An optical node.
raise_not_foundbool, optional; default: True: Raises a BeamTraceException if no dependency found. Returns None if False.

find_intersection_couplings(self, TraceForest other=None) → tuple

Finds the node couplings at which trees with differing trace dependencies intersect.

Parameters

otherTraceForest: Find dependencies from a different trace forest than this one when checking for intersections.

Returns

couplingstuple: A tuple of the node couplings where each element is (from_node, to_node).

find_potential_mismatch_couplings(self, TraceForest other=None) → tuple

Retrieves the node couplings which are potentially mode mismatched. If other is not given then the couplings which are local to this forest only will be found, otherwise couplings between this forest and other will be retrieved.

If this forest is asymmetric, then calling this method is equivalent to calling TraceForest.find_intersection_couplings().

This method is used internally for obtaining all the possible mode mismatch couplings between a changing trace forest (held by a modal simulation) and the main model trace forest.

Parameters

otherTraceForest: Find dependencies from a different trace forest than this one when checking for mode mismatch couplings.

Returns

couplingstuple: A tuple of the node couplings where each element is (from_node, to_node).

find_tree_from_node(self, node) → TraceTree

Given an optical node, this finds the TraceTree instance corresponding to this node (if one exists).

Parameters

nodeOpticalNode: An optical node.

Returns

treeTraceTree: The tree corresponding to node, or None if none found.

find_untraversed_nodes(self) → OrderedSet: Finds all the optical nodes in the model which are not covered by the trace forest.

forest

gauss_trees[source]

get_mirror_reflection_couplings(self, bool ignore_internal_cavities=True, list skip_dependencies=None) → tuple

Get the node couplings in the forest which correspond to self-reflections from mirror-like components.

Parameters

ignore_internal_cavitiesbool, default: True: Ignore the node couplings inside cavities.
skip_dependencieslist: Optional list of trees to skip based on their dependencies.

Returns

couplingstuple: A sequence of tuples consisting of the node1 -> node2 self reflection couplings.

get_nodes_with_changing_q(self)[source]

For a given TraceForest this method will determine which optical nodes in a model will have a changing complex beam parameter.

This relies on element Parameters having their is_tunable or is_changing being set as True. In such cases the Model will construct a simulation where the calculations dependent on these parameters will be recomputed at multiple steps.

Returns

q_changing_nodesset{OpticalNode}: Set of of OpticalNodes which will have a changing complex beam parameter during a simulation.

internal_cavity_trees[source]

make_changing_forest(self) → TraceForest

Constructs a new TraceForest from this forest, consisting of only the trees which will have changing beam parameters.

This method is called in BaseSimulation._initialise for setting up the simulation trace forest used for efficient beam tracing.

model

plant(self, list trace_order)[source]

Constructs and stores all the trace trees according to the order of dependencies in trace_order.

Parameters

trace_orderlist: List of the dependency objects by priority of tracing.

size(self) → Py_ssize_t: The number of trees in the forest.

symmetric: symmetric: ‘bool’

trace_beam(self) → dict

Performs a “model-time” beam trace on all trace trees.

This method is called internally by Model.beam_trace(). One should use that method to get a more complete representation of the tracing of the beam through a model.

Returns

tracedict: Dictionary of node: (qx, qy) mappings where node is each OpticalNode instance and qx, qy are the beam parameters in the tangential and sagittal planes, respectively, at these nodes.

trees_of_dependency(self, dependency) → list

Get a list of all the TraceTree instances with the associated trace dependency object.

Parameters

dependencyTraceDependency: A trace dependency object.

Returns

treeslist: A list of all trace trees with dependency equal to above object.

class finesse.tracing.forest.tree_container(list trees=None)[source]

Bases: object

A container of TraceTree objects.

Consists of a wrapper around a list of trees and a set of all the OpticalNode instances covered by this tree list. All of these attributes are read-only in the sense that they can only be accessed via C code.

trees[source]