finesse.tracing.ctracer.TraceForest

Overview

class finesse.tracing.ctracer.TraceForest(model)

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.

Methods

TraceForest.__init__(*args, **kwargs)

TraceForest.clear(self)

Clears the trace forest, removing all trace trees.

TraceForest.contains_comp(self, comp)

TraceForest.contains_space(self, space)

Whether this trace forest contains the specified space.

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

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

TraceForest.gather_nodes(self)

Generates a set of all the optical nodes covered by the forest.

TraceForest.get_mirror_reflection_couplings(...)

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

TraceForest.plant(self, list trace_order)

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