finesse.model.Model.beam_trace

Model.beam_trace(order=None, disable=None, enable_only=None, symmetric=True, store=True, solution_name='beam_trace')

Performs a full beam trace on the model, calculating the beam parameters at each optical node.

Beam tracing requires at least one stable TraceDependency object - defined as a Gauss or Cavity object - in the model. Note that Cavity objects are not determined automatically, they must be explicitly added to the model.

The order in which the beam tracing is performed is as follows:

• All internal cavity traces are carried out initially, i.e. any nodes that are part of a path of a Cavity instance in the model will be traced using the cavity eigenmode as the basis. See the note below for what happens in the case of overlapping cavities.

• If order is not specified, then the dependency ordering given by Model.trace_order is used; i.e. beam traces are performed from each dependency in this list where any overlapping trees from multiple dependencies will always use the first dependency’s tree.

• If order is specified, then beam traces from each dependency given in this argument will be carried out in the given order, in the same way as above. This effectively allows temporary overriding of the trace order for specific beam trace calls.

Certain dependencies can be switched off via the disable or enable_only arguments.

Full details on the beam tracing algorithm are given in Tracing the beam.

Note

Overlapping cavities

In complicated configurations, such as dual-recycled Michelson interferometers, it is often the case that there will be overlapping cavities; i.e. cavities which share common optical nodes in their paths. This naturally leads to the question - in which basis are these common nodes being set?

The algorithm used by this method will prioritise the internal trace of the cavity as follows:

• If order is not given then the cavity appearing first in Model.trace_order will be used for setting the beam parameters of all nodes in this cavity path - including any nodes which are shared with other cavity instances.

• Otherwise, the cavity appearing first in order will be used in the same way.

Parameters

ordersequence, optional; default: None

A priority list of dependencies to trace in order. These dependencies can be either Cavity / Gauss objects or the names of these objects. If this argument is not specified then beam tracing will be performed using the order defined in Model.trace_order.

This argument allows temporary overriding of the model trace order for a given beam trace call, without needing to change the TraceDependency.priority values of any dependencies in the model (which would affect all future beam traces in which order is not specified). Note that, if specifying this argument, a sub-set of the trace dependencies in the model can be given — any dependencies not in the given order will retain their original ordering.

disablesequence, optional: default: None

A single dependency or list of dependencies to disable. These dependencies can be either Cavity / Gauss objects or the names of these objects.

Note that this argument is ignored if enable_only is specified.

enable_onlysequence, optional: default: None

A single dependency or list of dependencies to explicity enable, all other dependencies will be switched off for the trace call. These dependencies can be either Cavity / Gauss objects or the names of these objects.

symmetricbool, optional; default: true

Flag to determine whether the beam parameters at OpticalNode.opposite nodes of each node encountered during the beam trace get set to the BeamParam.reverse() of the “forward” propagated beam parameter.

storebool, optional; default: True

Flag to determine whether to store the results of a beam trace in in the Model.last_trace property. Note that if this is set to False then accessing beam parameters via OpticalNode instances directly will give the last stored beam parameter at that node (i.e. not those given by this trace call).

Returns

outBeamTraceSolution

An object representing the results of the tracing routine.

Raises

exBeamTraceException

If there are no Gauss objects or stable Cavity instances present in the model.

ex_v: ValueError

If order was specified and it contains an invalid item.

ex_trTotalReflectionError

If a Beamsplitter object is present in the model with an angle of incidence and associated refractive indices giving total internal reflection.