finesse.detectors.workspace module

class finesse.detectors.workspace.DetectorWorkspace(owner, sim, values=None, OutputInformation oinfo=None, *, bool needs_carrier=False, bool needs_signal=False, bool needs_noise=False, bool needs_modal_update=False, bool needs_simulation=True)

Bases: ElementWorkspace

A base class that all detector workspaces should inherit from. Provides a generic set of data needed to compute values and output them with metadata needed for storing the outputs.

Parameters

ownerfinesse.element.ModelElement

Detector Element that owns this workspace and will be setting it up

simSimulation object

Simulation object this workspace should be associated with

values[object, finesse.element_workspace.BaseCValues], optional

The object containing the values that will be used by this workspace to calculate some output. These should match the parameters offered by the owner. A pure Python object can be used but will be slower to access. A finesse.element_workspace.BaseCValues object can also be used that offers cythonised access to parameter values

oinfoOutputInformation, optional

When provided this will set the output information of this detector, such as units, datatype, shape/dimension of outputs.

needs_carrierbool, optional

If the carrier simulation data is needed, this must be True

needs_signalbool, optional

If the signal simulation data (transfer functions) is needed, this must be True

needs_noisebool, optional

If this detector requires noise covariances to be calculated this must be True

needs_modal_update: bool, optional

If this detector outputs some modal or geometric property, this must be True.

Notes

The needs_* flags specify which simulations should be run to evaluate this workspace. At least one should be True, unless needs_simulation is flagged as False. This is to catch certain cases which mean the workspace will just not produce any output.

When adding new needs_* flag, ensure you update the MathDetector object to correctly fill these flags. The MathDetector essentially borrows workspaces from other detectors to compute its output and

get_output(self)

needs_carrier

needs_modal_update

needs_noise

needs_signal

oinfo

set_output_fn(self, callback)

class finesse.detectors.workspace.MaskedDetectorWorkspace(owner, BaseSimulation sim, values=None, oinfo=None, *, **kwargs)

Bases: DetectorWorkspace

Specialised workspace for detectors which support masking of modes.

This workspace provides attributes that are exposed to both C and Python. The sections below detail how to use these for some workspace instance ws which inherits from MaskedDetectorWorkspace.

Using via Python

The unmasked_indices_arr attribute is a numpy.ndarray, of dtype np.intp, which contains the indices of modes which are not masked. One may then simply loop over this array of indices to access the corresponding field indices, e.g

for k in ws.unmasked_indices_arr:
    # Do something with k, e.g. get field at 0 Hz freq. offset
    # at the given node for the mode index k:
    a_0k = carrier.get_out_fast(ws.dc_node_id, 0, k)
    # use a_0k for some calculation ...

Using via Cython

This workspace also provides a unmasked_mode_indices pointer (only accessible from other Cython code) which corresponds to the data of the unmasked_indices_arr NumPy array described above. The attribute num_unmasked_homs is the size of this array; i.e. the number of modes which are not masked.

One may then write an optimised loop from [0, num_unmasked_homs), e.g

cdef Py_ssize_t i, k
cdef complex_t a_0k
for i in range(ws.num_unmasked_homs):
    k = ws.unmasked_mode_indices[i]
    # Do something with k, e.g. get field at 0 Hz freq. offset
    # at the given node for the mode index k:
    a_0k = carrier.get_out_fast(ws.dc_node_id, 0, k)
    # use a_0k for some calculation ...

where each k is then the index of the mode at position i in the unmasked indices array.

Note

If the detector mask is empty (i.e. no modes are being masked) then unmasked_indices_arr (and, correspondingly, unmasked_mode_indices) will simply be an array from [0, Nhoms) where Nhoms is the total number of modes in the simulation.

has_mask

num_unmasked_HOMs

unmasked_indices_arr

class finesse.detectors.workspace.OutputFuncWrapper

Bases: object

Helper class for wrapping a C fill function that can be referenced from Python by objects. This allows a direct C call to the function from other cdef functions.

Examples

Create a C function then wrap it using this class:

>>> cdef void c_output(DetectorWorkspace ptr_ws) noexcept:
>>>    cdef PDWorkspace ws = <PDWorkspace>ptr_ws
>>>    ...
>>>
>>> fill = OutputFuncWrapper.make_from_ptr(c_fill)

class finesse.detectors.workspace.OutputInformation(name, detector_type, nodes, dtype, unit, shape, label, needs_fields, needs_trace)

Bases: object

detector_type

The type of the detector that has generated this output information.

dtype

dtype_shape

dtype_size

Size of the output in terms of number of elements.

This is typically unity as most detectors return a single value via their output functions.

Equivalent to the product of Detector.dtype_shape.

label

name

needs_fields

Flag indicating whether the detector requires light fields (i.e. solving of the interferometer matrix).

needs_trace

Flag indicating whether the detector requires beam traces.

nodes

The nodes this detector observes.

Getter:

Returns copy of detected nodes.

unit