finesse.tracing.forest.TraceForest

Overview

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

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().

Properties

TraceForest.external_cavity_trees

TraceForest.gauss_trees

TraceForest.internal_cavity_trees

Methods

TraceForest.__init__(*args, **kwargs)

TraceForest.clear(self)

Clears the trace forest, removing all trace trees.

TraceForest.contains(self, o)

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

TraceForest.draw(self)

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

TraceForest.draw_by_dependency(self)

Draws the forest as a string representation.

TraceForest.empty(self)

Whether the forest is empty (no trees) or not.

TraceForest.find_dependency_from_node(self, ...)

Finds the dependency object associated with the optical node.

TraceForest.find_intersection_couplings(...)

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

TraceForest.find_potential_mismatch_couplings(...)

Retrieves the node couplings which are potentially mode mismatched.

TraceForest.find_tree_from_node(self, node)

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

TraceForest.find_untraversed_nodes(self)

Finds all the optical nodes in the model which are not covered by the trace forest.

TraceForest.get_mirror_reflection_couplings(...)

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

TraceForest.get_nodes_with_changing_q(self)

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

TraceForest.make_changing_forest(self)

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

TraceForest.plant(self, list trace_order)

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

TraceForest.size(self)

The number of trees in the forest.

TraceForest.trace_beam(self)

Performs a "model-time" beam trace on all trace trees.

TraceForest.trees_of_dependency(self, dependency)

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