finesse.tracing.tree module

The TraceTree data structure and associated algorithms.

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.tree.TraceTree(node, dependency)[source]

Bases: object

A binary tree data structure representing all the beam tracing paths from some root optical node of a model.

Each instance of this class has a left and right sub-tree (of the class type) and a parent tree. These linked tree attributes can be None. If the tree has a left / right sub-tree then the memoryviews left_abcd_x, left_abcd_y etc. will be initialised from the numerical ABCD matrix from the tree’s optical node to the next tree’s optical node.

Every sub-tree has a dependency attribute which is the object that the trace tree depends on - either a Cavity or a gauss instance.

add_left(self, TraceTree sub_tree) → TraceTree

Add a left sub-tree to the tree.

Parameters

sub_treeTraceTree: The tree to add to the left.

Returns

sub_treeTraceTree: The same tree that was added. This is useful for looping over a single branch of the tree as a parent tree can be set to the return of this method on each iteration.

add_right(self, TraceTree sub_tree) → TraceTree

Add a right sub-tree to the tree.

Parameters

sub_treeTraceTree: The tree to add to the right.

Returns

sub_treeTraceTree: The same tree that was added. This is useful for looping over a single branch of the tree as a parent tree can be set to the return of this method on each iteration.

compute_rt_abcd(self, double[, : :1] abcdx = None, double[, : :1] abcdy = None)[source]

contains(self, o) → bool

Whether the tree contains the specified object, determined recursively.

Parameters

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

Returns

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

dependency

draw(self, str left_pad='')[source]

find_tree_at_node(self, node, bool include_opposite=False) → TraceTree: Recursively search for the TraceTree corresponding to the optical node.

classmethod from_cavity(cls, cavity)[source]

Construct a TraceTree from a cavity instance.

The resulting tree decays to a linked list as it just includes the internal path of the cavity.

Parameters

cavityCavity: The cavity object.

Returns

treeTraceTree: The tree representing the internal cavity path.

classmethod from_node(cls, node, dependency, bool symmetric, pre_node=None, bool is_source=False, exclude=None)[source]

Construct a TraceTree from an optical node root.

The resulting tree includes all optical node paths traced forward from node.

Parameters

nodeOpticalNode: The root node.
dependencyCavity or Gauss: The dependency object - i.e. what the trace sub-trees depend on.
symmetricbool: Flag indicating whether the tree should be constructed assuming that opposite node beam parameters will be set via the reverse of the original node beam parameter (true indicates this will be the case). In practice, this means that the resultant tree will not include any duplicate ports.
pre_nodeOpticalNode, optional; default: None: An optional node to add before the root for the root sub-tree.
is_sourcebool, optional; default: False: Whether the root node is the source node of a TraceDependency.
excludeset, optional: Set of optical nodes to avoid branching to.

Returns

treeTraceTree: The tree of all paths from node.

static from_path(list path)[source]

Construct a TraceTree from a list of optical nodes.

The resulting tree decays to a linked list as the path is 1D - no branches will occur.

Parameters

pathlist: A list of optical nodes representing the node path. This can be obtained from a OpticalPath instance by invoking OpticalPath.nodes.

Returns

treeTraceTree: The tree representing the node path.

get_all_nodes(self) → OrderedSet

Retrieve a set consisting of all the OpticalNode objects covered by this tree.

Returns

nodesset: A set of all the optical nodes in the tree.

get_broadest_changing_subtrees(self) → list: Retrieve a list of each TraceTree, from here, which is changing.

get_last_input_nodes(self) → list: Retrieves a list of the final input optical nodes within the tree.

get_last_left_branch(self) → TraceTree: Finds the final left sub-tree from this tree node.

get_mirror_reflection_couplings(self) → list: Obtain a list of all the node couplings corresponding to self-reflections.

is_changing(self, bool recursive=True) → bool

is_left_surf_refl

is_source

is_x_changing

is_y_changing

left

left_abcd_x

left_abcd_x_args

left_abcd_x_kwargs

left_abcd_x_target

left_abcd_y

left_abcd_y_args

left_abcd_y_kwargs

left_abcd_y_target

node

nr

parent

propagate(self, dict trace, double lambda0, bool symmetric)[source]

remove_left(self) → TraceTree

Removes the left sub-tree and returns it.

Sets the left trace tree attribute to None, and nullifies left ABCD memory-views and pointers.

Returns

ltreeTraceTree: The removed left sub-tree.

remove_right(self) → TraceTree

Removes the right sub-tree and returns it.

Sets the right trace tree attribute to None, and nullifies right ABCD memory-views and pointers.

Returns

rtreeTraceTree: The removed right sub-tree.

right

right_abcd_x

right_abcd_x_args

right_abcd_x_kwargs

right_abcd_x_target

right_abcd_y

right_abcd_y_args

right_abcd_y_kwargs

right_abcd_y_target

set_left_abcd_x_memory(self, target, *args, **kwargs)[source]: Set the left ABCD matrix memory-views from the target function. Stores where this ABCD matrix came from for later retrieval and recreation if copied or pickled.

set_left_abcd_y_memory(self, target, *args, **kwargs)[source]: Set the left ABCD matrix memory-views from the target function. Stores where this ABCD matrix came from for later retrieval and recreation if copied or pickled.

set_right_abcd_x_memory(self, target, *args, **kwargs)[source]: Set the right ABCD matrix memory-views from the target function. Stores where this ABCD matrix came from for later retrieval and recreation if copied or pickled.

set_right_abcd_y_memory(self, target, *args, **kwargs)[source]: Set the right ABCD matrix memory-views from the target function. Stores where this ABCD matrix came from for later retrieval and recreation if copied or pickled.

sym_left_abcd_x

sym_left_abcd_y

sym_right_abcd_x

sym_right_abcd_y

trace_beam(self, double lambda0, bool symmetric) → dict: Trace the beam through the source tree.

trim_at_nodes(self, nodes, bool include_opposite=False)[source]: Trims branches from the tree starting at any optical node in nodes.

finesse.tracing.tree.get_tracing_tree(optical_network: networkx.DiGraph) → networkx.DiGraph[source]: Creates a view of an optical network that removes edges that should not be ABCD traced. These are determined by checking the objects Connector._trace_through flag.