Processing Objects API

Processing objects for simulating AO system components.

Abstract Coronagraph

class specula.processing_objects.abstract_coronagraph.Coronagraph(simul_params: SimulParams, wavelengthInNm: float, fov: float, fov_errinf: float = 0.1, fov_errsup: float = 10, fft_res: float = 3.0, center_on_pixel: bool = True, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Abstract coronagraph class processing object. This class provides the basic structure for a coronagraph processing object.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters containing pixel_pupil and pixel_pitch

• wavelengthInNm (float) – Wavelength in nm

• fov (float) – Desired field of view in lambda/D on focal plane

• fov_errinf (float, optional) – Relative error allowed on the inner part of the FOV (default: 0.1)

• fov_errsup (float, optional) – Relative error allowed on the outer part of the FOV (default: 10)

• fft_res (float, optional) – Desired resolution in the focal plane in pixels per lambda/D (default: 3.0)

• center_on_pixel (bool, optional) – Whether to center the focal plane mask on a single pixel (True) or at the intersection of 4 pixels (False). This affects the phase shift applied to the electric field (default: True)

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

make_apodizer()

Override this method to add an apodizer. By default, no apodizer mask is considered

abstractmethod make_focal_plane_mask()

Override this method to create the desired focal plane (complex) mask

abstractmethod make_pupil_plane_mask()

Override this method to create the desired pupil plane (complex) mask

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

App Coronagraph

class specula.processing_objects.app_coronagraph.APPCoronagraph(simul_params: SimulParams, wavelengthInNm: float, pupil, contrastInDarkHole: float, iwaInLambdaOverD: float, owaInLambdaOverD: float, fft_res: float = 3.0, make_symmetric: bool = False, beta: float = 0.9, max_its: int = 1000, target_device_idx: int = None, precision: int = None)

Bases: Coronagraph

Apodizing Phase Plate (APP) coronagraph class. This class implements an APP coronagraph, which uses a phase-only mask in the pupil plane to create a dark hole in the focal plane.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
define_apodizing_phase
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters containing pixel_pupil and pixel_pitch

• wavelengthInNm (float) – Wavelength in nm

• fov (float) – Desired field of view in lambda/D on focal plane

• fov_errinf (float, optional) – Relative error allowed on the inner part of the FOV (default: 0.1)

• fov_errsup (float, optional) – Relative error allowed on the outer part of the FOV (default: 10)

• fft_res (float, optional) – Desired resolution in the focal plane in pixels per lambda/D (default: 3.0)

• center_on_pixel (bool, optional) – Whether to center the focal plane mask on a single pixel (True) or at the intersection of 4 pixels (False). This affects the phase shift applied to the electric field (default: True)

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
define_apodizing_phase
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

define_apodizing_phase(pupil, contrast, iwa: float, owa: float, beta: float, symmetric_dark_hole: bool = False, max_its: int = 1000)

classmethod input_names()

make_focal_plane_mask()

Override this method to create the desired focal plane (complex) mask

make_pupil_plane_mask()

Override this method to create the desired pupil plane (complex) mask

classmethod output_names()

specula.processing_objects.app_coronagraph.generate_app_keller(pupil, target_contrast, max_iterations: int, xp, complex_dtype, beta: float = 0)

Function taken from HCIpy (Por et al. 2018): https://github.com/ehpor/hcipy/blob/master/hcipy/coronagraphy/apodizing_phase_plate.py

Accelerated Gerchberg-Saxton-like algorithm for APP design by Christoph Keller [Keller2016] and based on Douglas-Rachford operator splitting. The acceleration was inspired by the paper by Jim Fienup [Fienup1976]. The acceleration can provide speed-ups of up to two orders of magnitude and produce better APPs.

[Keller2016]

Keller C.U., 2016, “Novel instrument concepts for characterizing directly imaged exoplanets”, Proc. SPIE 9908, Ground-based and Airborne Instrumentation for Astronomy VI, 99089V doi: 10.1117/12.2232633; https://doi.org/10.1117/12.2232633

[Fienup1976]

J. R. Fienup, 1976, “Reconstruction of an object from the modulus of its Fourier transform,” Opt. Lett. 3, 27-29

Parameters:

• pupil (ndarray(bool) [1]) – Boolean of the pupil aperture mask.

• target_contrast (ndarray(float) [1]) – The required contrast in the focal plane: float mask that is 1.0 everywhere except for the dark zone where it is the contrast value (e.g. 1e-5).

• max_iterations (int [1]) – The maximum number of iterations.

• beta (float [1] (optional)) – The acceleration parameter. The default is 0 (no acceleration). Good values for beta are typically between 0.3 and 0.9. Values larger than 1.0 will not work.

Returns:

The APP as a wavefront.

Return type:

Wavefront

Raises:

ValueError – If beta is not between 0 and 1. If fft_res is less than 3.

Atmo Evolution

class specula.processing_objects.atmo_evolution.AtmoEvolution(simul_params: SimulParams, L0: list, heights: list, Cn2: list, data_dir: str = '', fov: float = 0.0, pixel_phasescreens: int = 8192, seed: int = 1, extra_delta_time: float = 0, fov_in_m: float = None, pupil_position: list = [0, 0], target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Atmospheric turbulence evolution processing object. Generates and evolves atmospheric phase screens based on input parameters such as seeing, wind speed, and wind direction.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
compute
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

Phase screens are always generated at a reference wavelength of 500 nm.

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing global simulation settings.

• L0 (list [m]) – Outer scale(s) of turbulence for each layer in meters.

• heights (list [m]) – Heights of the atmospheric layers in meters (at zenith).

• Cn2 (list [1]) – Fractional Cn2 values for each layer (must sum to 1.0).

• data_dir (str) – Directory path for storing/loading phase screen data (automatically set by simul.py).

• fov (float [arcsec], optional) – Field of view in arcseconds. Default is 0.0.

• pixel_phasescreens (int [1], optional) – Size of the square phase screens in pixels. Default is 8192.

• seed (int [1], optional) – Seed for random number generation. Must be >0. Default is 1.

• extra_delta_time (float or list [s], optional) – Extra time offset for phase screen evolution in seconds. Default is 0.

• fov_in_m (float [m], optional) – Field of view in meters. If provided, overrides fov parameter. Default is None.

• pupil_position (list [m], optional) – [x, y] position of the pupil in meters. Default is [0, 0].

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
compute
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

compute()

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Atmo Evolution Up Down

class specula.processing_objects.atmo_evolution_up_down.AtmoEvolutionUpDown(simul_params: SimulParams, L0: list, heights: list, Cn2: list, data_dir: str, extra_delta_time_down: float = 0, extra_delta_time_up: float = 0, fov: float = 0.0, pixel_phasescreens: int = 8192, seed: int = 1, fov_in_m: float = None, pupil_position: list = [0, 0], target_device_idx: int = None, precision: int = None)

Bases: AtmoEvolution

Atmospheric turbulence evolution processing object with separate layer lists for upward and downward propagation. This class extends AtmoEvolution to provide two independent layer lists with different extra_delta_time values.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Update both downward and upward layer lists with different time offsets.

addRemoteOutput
build_stream
capture_stream
check_ready
compute
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

It is useful for simulating satellite laser communication where uplink and downlink paths experience different temporal offsets.

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing global simulation settings.

• L0 (list [m]) – Outer scale(s) of turbulence for each layer in meters.

• heights (list [m]) – Heights of the atmospheric layers in meters (at zenith).

• Cn2 (list [1]) – Fractional Cn2 values for each layer (must sum to 1.0).

• data_dir (str) – Directory path for storing/loading phase screen data.

• extra_delta_time_down (float or list [s], optional) – Extra time offset for downward propagation in seconds. Default is 0.

• extra_delta_time_up (float or list [s], optional) – Extra time offset for upward propagation in seconds. Default is 0.

• fov (float [arcsec], optional) – Field of view in arcseconds. Default is 0.0.

• pixel_phasescreens (int [1], optional) – Size of the square phase screens in pixels. Default is 8192.

• seed (int [1], optional) – Seed for random number generation. Must be >0. Default is 1.

• fov_in_m (float [m], optional) – Field of view in meters. If provided, overrides fov parameter. Default is None.

• pupil_position (list [m], optional) – [x, y] position of the pupil in meters. Default is [0, 0].

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Update both downward and upward layer lists with different time offsets.

addRemoteOutput
build_stream
capture_stream
check_ready
compute
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod output_names()

trigger_code()

Update both downward and upward layer lists with different time offsets.

Atmo Infinite Evolution

class specula.processing_objects.atmo_infinite_evolution.AtmoInfiniteEvolution(simul_params: SimulParams, L0: list = [1.0], heights: list = [0.0], Cn2: list = [1.0], fov: float = 0.0, seed: int = 1, extra_delta_time: float = 0, fov_in_m: float = None, pupil_position: list = [0, 0], target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Atmospheric infinite phase screens evolution processing object. Generates and evolves atmospheric phase screens based on input parameters such as seeing, wind speed, and wind direction.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
initScreens
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger
trigger_code

Note

Phase screens are always generated at a reference wavelength of 500 nm.

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing global simulation settings.

• L0 (list [m]) – Outer scale(s) of turbulence for each layer in meters.

• heights (list [m]) – Heights of the atmospheric layers in meters (at zenith).

• Cn2 (list [1]) – Fractional Cn2 values for each layer (must sum to 1.0).

• data_dir (str) – Directory path for storing/loading phase screen data (automatically set by simul.py).

• fov (float [arcsec], optional) – Field of view in arcseconds. Default is 0.0.

• pixel_phasescreens (int [1], optional) – Size of the square phase screens in pixels. Default is 8192.

• seed (int [1], optional) – Seed for random number generation. Must be >0. Default is 1.

• extra_delta_time (float or list [s], optional) – Extra time offset for phase screen evolution in seconds. Default is 0.

• fov_in_m (float [m], optional) – Field of view in meters. If provided, overrides fov parameter. Default is None.

• pupil_position (list [m], optional) – [x, y] position of the pupil in meters. Default is [0, 0].

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
initScreens
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger
trigger_code

initScreens(seed)

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code(**kwargs)

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Atmo Infinite Evolution Up Down

class specula.processing_objects.atmo_infinite_evolution_up_down.AtmoInfiniteEvolutionUpDown(simul_params: SimulParams, L0: list = [1.0], heights: list = [0.0], Cn2: list = [1.0], extra_delta_time_down: float = 0, extra_delta_time_up: float = 0, fov: float = 0.0, seed: int = 1, fov_in_m: float = None, pupil_position: list = [0, 0], target_device_idx: int = None, precision: int = None)

Bases: AtmoInfiniteEvolution

Atmospheric infinite phase screens evolution processing object with separate layer lists for upward and downward propagation. This class extends AtmoInfiniteEvolution to provide two independent layer lists with different extra_delta_time values.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Update both lists by saving/restoring phase screen state.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
initScreens
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing global simulation settings.

• L0 (list [m]) – Outer scale(s) of turbulence for each layer in meters.

• heights (list [m]) – Heights of the atmospheric layers in meters (at zenith).

• Cn2 (list [1]) – Fractional Cn2 values for each layer (must sum to 1.0).

• extra_delta_time_down (float or list [s], optional) – Extra time offset for downward propagation in seconds. Default is 0.

• extra_delta_time_up (float or list [s], optional) – Extra time offset for upward propagation in seconds. Default is 0.

• fov (float [arcsec], optional) – Field of view in arcseconds. Default is 0.0.

• seed (int [1], optional) – Seed for random number generation. Must be >0. Default is 1.

• fov_in_m (float [m], optional) – Field of view in meters. If provided, overrides fov parameter. Default is None.

• pupil_position (list [m], optional) – [x, y] position of the pupil in meters. Default is [0, 0].

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Update both lists by saving/restoring phase screen state.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
initScreens
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod output_names()

trigger_code()

Update both lists by saving/restoring phase screen state.

Atmo Propagation

class specula.processing_objects.atmo_propagation.AtmoPropagation(simul_params: SimulParams, source_dict: dict, doFresnel: bool = False, wavelengthInNm: float = 500.0, telescope_altitude_m: float = None, enable_chromatic_effect: bool = False, chromatic_reference_wavelengthInNm: float = None, pupil_position=None, mergeLayersContrib: bool = True, upwards: bool = False, padding_factor: int = 1, beam_center=None, target_device_idx=None, precision=None)

Bases: BaseProcessingObj

Atmospheric propagation processing object. This processing object simulates the propagation of light through atmospheric turbulence layers. It can perform both geometric and physical (Fresnel) propagation, depending on the configuration.

Methods

asm_propagator(distanceInM, d_in, d_out)	Jason D.
calc_propagators(z)	Calculate propagators based on distance.
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
compute_chromatic_shifts(source, atmo_layer_list)	Pre-compute the chromatic lateral displacement for each atmospheric layer.
finalize()	Override this method to perform any actions after the simulation is completed
fraunhofer_propagator(distanceInM)	Jason D.
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.

addRemoteOutput
angular_spectrum_propagation
build_stream
capture_stream
check_ready
device_stream
doFresnel_setup
fraunhofer_far_field_propagation
init_logging
input_names
layer_interpolator
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
setup_interpolators
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger
trigger_code

Note

• By default, all atmospheric phase screens are referenced to a wavelength of 500 nm.

• Layer heights are always defined at zenith and projected according to the simulation

zenith angle (coming from simul_params).

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing global settings.

• source_dict (dict) – Dictionary of source objects (e.g., stars, LGS) to be propagated.

• doFresnel (bool) – If True, physical Fresnel propagation is performed. Default is False (geometric propagation).

• wavelengthInNm (float [nm], optional) – Wavelength in nanometers for Fresnel propagation. Required if doFresnel is True. Default is 500.0 nm.

• telescope_altitude_m (float [m], optional) – Telescope altitude above sea level in meters used by chromatic anisoplanatism calculations (default: None).

• enable_chromatic_effect (bool) – If True, compute and apply chromatic anisoplanatism shifts for atmospheric layers (default: False). From Devaney et al. “Chromatic Anisoplanatism in Adaptive Optics” SPIE, 2024

• chromatic_reference_wavelengthInNm (float [nm], optional) – Reference wavelength in nanometers used for chromatic anisoplanatism calculations, typically the WFS wavelength. Required when enable_chromatic_effect is True.

• pupil_position (array-like [m], optional) – Position of the pupil in pixels. Default is None (centered).

• mergeLayersContrib (bool) – If True, contributions from all layers are merged into a single output per source. Default is True.

• upwards (bool) – If True, propagation is performed upwards (from ground to source). Default is False (downwards).

• padding_factor (int [1], optional) – Factor for zero padding in Fresnel propagation to avoid numerical issues with FFTs.

• beam_center (float [1], optional) – Center of Gaussian uplink beam in pixel. Used for Fraunhofer propagation.

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

asm_propagator(distanceInM, d_in, d_out)	Jason D.
calc_propagators(z)	Calculate propagators based on distance.
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
compute_chromatic_shifts(source, atmo_layer_list)	Pre-compute the chromatic lateral displacement for each atmospheric layer.
finalize()	Override this method to perform any actions after the simulation is completed
fraunhofer_propagator(distanceInM)	Jason D.
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.

addRemoteOutput
angular_spectrum_propagation
build_stream
capture_stream
check_ready
device_stream
doFresnel_setup
fraunhofer_far_field_propagation
init_logging
input_names
layer_interpolator
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
setup_interpolators
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger
trigger_code

angular_spectrum_propagation(ef_in, propagator)

asm_propagator(distanceInM, d_in, d_out)

Jason D. Schmidt, Numerical Simulation of Optical Wave Propagation with Examples in MATLAB Computes the propagators used for the Angular Spectrum Propagation Method. Applies an automatic scaling if the input grid spacing d_in is not equal to the output grid spacing d_out.

Parameters:

• distanceInM (float [m]) – Propagation distance in meter.

• d_in (float [m]) – Grid spacing in the source plane

• d_out (float [m]) – Grid spacing in the destination plane

calc_propagators(z)

Calculate propagators based on distance.

For far-field propagation Fraunhofer is used, otherwise angular spectrum propagation (ASM) method. Propagation distance is automatically reduced to avoid numerical issues with FFTs.

check_output_names()

Check that all output names declared in self.output_names are present in self.outputs

Supported declaration grammar for output names: - Exact names, e.g. out_ef

• Placeholder patterns, e.g. out_modes_{sensor_idx}

  (ModalrecMultirate)

• Placeholder patterns, e.g. out_{source_name_}layer

  (AtmoRandomPhase)

Notes

• Placeholder segments {...} are treated as wildcards.

  • In project classes, placeholder-style declarations are mandatory;

    do not use raw * declarations in output_names().

• Exact-key matches take precedence over pattern matches.

compute_chromatic_shifts(source, atmo_layer_list)

Pre-compute the chromatic lateral displacement for each atmospheric layer.

Uses the MatharAirRefraction (Ciddor+Mathar) model to calculate precise refractivity across Visible and Mid-IR bands. Then applies the NASA standard atmospheric pressure profile to compute the exact lateral shift using the Devaney 2024 plane-parallel equations (Eq. 1 and Eq. 6).

The result is stored in self.chromatic_shifts_m as a dict keyed by Source and Layer objects, containing the signed lateral displacement in metres. Common layers (pupil stop, DM, etc.) are not included and will implicitly receive a zero shift in the propagation code.

This method must be called before the interpolators are built.

Parameters:

• atmo_layer_list (list of Layer) – Atmospheric turbulence layers only (not common layers such as pupil stops or DMs).

• zenith_angle_deg (float [deg]) – Observation zenith angle in degrees.

Notes

If enable_chromatic_effect is False or the two wavelengths are identical, all shifts are zero.

doFresnel_setup()

fraunhofer_far_field_propagation(ef_in, propagator)

fraunhofer_propagator(distanceInM)

Jason D. Schmidt, Numerical Simulation of Optical Wave Propagation with Examples in MATLAB Computes the propagators used for Fraunhofer far-field propagation.

Parameters:

distanceInM (float [m]) – Propagation distance in meter.

classmethod input_names()

layer_interpolator(source, layer)

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

setup_interpolators()

trigger_code(**kwargs)

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Atmo Random Phase

class specula.processing_objects.atmo_random_phase.AtmoRandomPhase(simul_params: SimulParams, L0: float = 1.0, data_dir: str = '', source_dict: dict = None, wavelengthInNm: float = 500.0, pixel_phasescreens: int = 8192, seed: int = 1, update_interval: int = 1, layer_height: float = 0.0, target_device_idx=None, precision=None)

Bases: BaseProcessingObj

Atmospheric random phase screen generator processing object. Atmospheric phase screen generator producing random (uncorrelated) phase screens.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
initScreens
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing pupil size, pixel pitch, zenith angle, etc.

• L0 (float [m], optional) – Outer scale of turbulence in meters, by default 1.0

• data_dir (str) – Directory path for storing/loading phase screen data (automatically set by simul.py).

• source_dict (dict [1], optional) – Dictionary of sources for the atmospheric phase screens. If omitted or empty, the object exposes a single pair of outputs named out_ef and out_layer.

• wavelengthInNm (float [nm], optional) – Wavelength in nanometers for scaling the phase screens, by default 500.0 nm

• pixel_phasescreens (int [1], optional) – Size of the square phase screens in pixels. Defaults to 8192.

• seed (int [1], optional) – Seed for random number generation, by default 1.

• update_interval (int [1], optional) – Number of triggers between phase screen updates, by default 1.

• layer_height (float [m], optional) – Height in meters assigned to the output layers, by default 0.0.

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
initScreens
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

initScreens()

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Avc

class specula.processing_objects.avc.AVC(target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Active Vibration Cancellation processing object.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

Base Filter

class specula.processing_objects.base_filter.BaseFilter(nfilter: int, delay: float = 0, target_device_idx=None, precision=None)

Bases: BaseProcessingObj

Base filter processing object. Base class for time-domain filters with delay support.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset filter internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement filter-specific computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

Provides common functionality for:

• Delay buffer management

• Interpolation for fractional delays

• Gain modulation

• Synchronous (no-delay) outputs for POLC

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset filter internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement filter-specific computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

abstractmethod reset_states()

Reset filter internal states.

abstractmethod trigger_code()

Implement filter-specific computation.

Must populate self.output_buffer[:, 0] with current output.

Base Generator

class specula.processing_objects.base_generator.BaseGenerator(output_size: int = 1, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Base Generator processing object. Base class for function generators. All specific generators inherit from this class and implement trigger_code().

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Implement signal generation logic in subclasses

Base Inserter

class specula.processing_objects.base_inserter.BaseInserter(output_size, indices=None, slice_args=None, target_device_idx=None, precision=None)

Bases: BaseProcessingObj

Base Inserter processing object. Inserts a small vector into a larger. Mirrors the BaseSlicer interface, but for insertion.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• output_size (int [1]) – Size of the large output vector.

• indices (list of [src_indices, dest_indices] pairs, optional) – Each pair defines explicit indices in the input and output vectors. Example: indices=[[0,1,2], [1,3,5]] inserts src[0,1,2] into dest[1,3,5].

• slice_args (list of [src_slice_args, dest_slice_args] pairs, optional) – Each pair defines a slice in the input and output vectors. Example: slice_args=[[0,3], [2,5]] inserts src[0:3] into dest[2:5]. Multiple pairs: slice_args=[[[0,2],[0,2]], [[2,4],[5,7]]]

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Base Modalrec

class specula.processing_objects.base_modalrec.BaseModalrec(target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Base Modal Reconstructor processing object. Handles common slope inputs, modal outputs, and memory allocation for all modal reconstructors. Specific algorithms implement trigger_code().

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Base Operation

class specula.processing_objects.base_operation.BaseOperation(constant_mul: float = None, constant_div: float = None, constant_sum: float = None, constant_sub: float = None, constant_max: float = None, constant_min: float = None, mul: bool = False, div: bool = False, sum: bool = False, sub: bool = False, concat: bool = False, value2_remap: list = None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Base Operation processing object. Simple operations with base value(s).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Base operation processing object.

Applies a sequence of element-wise operations to an input value (value1), optionally combining it with a second input (value2). The operation supports constant-based transformations as well as a single binary operation between two inputs.

Parameters:

• constant_mul (float or array-like [1], optional) – Constant factor for element-wise multiplication.

• constant_div (float or array-like [1], optional) – Constant divisor for element-wise division.

• constant_sum (float or array-like [1], optional) – Constant added element-wise.

• constant_sub (float or array-like [1], optional) – Constant subtracted element-wise.

• constant_max (float or array-like [1], optional) – Element-wise lower bound (applies maximum(result, constant_max)).

• constant_min (float or array-like [1], optional) – Element-wise upper bound (applies minimum(result, constant_min)).

• mul (bool) – If True, multiply the result with value2.

• div (bool) – If True, divide the result by value2.

• sum (bool) – If True, add value2 to the result.

• sub (bool) – If True, subtract value2 from the result.

• concat (bool) – If True, concatenate value1 and value2 before applying constant operations.

• value2_remap (list of int, optional) – Optional index mapping applied to value2 before the binary operation. Cannot be used together with concat.

• target_device_idx (int [1], optional) – Target device index (CPU/GPU). If None, a global setting is used.

• precision (int [1], optional) – Precision for computation (0 = double, 1 = single). If None, a global setting is used.

Raises:

• ValueError – If more than one of sum, sub, mul, div or concat is True.

• ValueError – If concat is True and value2_remap is provided.

• ValueError – If a binary operation is requested but value2 is not set during setup.

Notes

Execution order

Operations are applied in the following order:

1. Concatenation (if concat=True)

2. Constant multiplication and division

3. Constant addition and subtraction

4. Constant min/max (clamping)

5. Binary operation with value2 (if enabled)

In pseudo-code:

result = value1

if concat:
    result = concat(result, value2)

result *= constant_mul
result /= constant_div

result += constant_sum
result -= constant_sub

result = maximum(result, constant_max)
result = minimum(result, constant_min)

result = result (op) value2

where (op) is one of +, -, *, /.

Broadcasting semantics

Constant operations are applied using in-place operators (e.g. *=, +=). As a result:

• Broadcasting is supported only if it does not change the shape of the

left-hand side (value1). - Shape-expanding broadcasts (e.g. from shape (1,) to (N,)) are not allowed and will raise an exception.

Examples:

value shape (3,), constant scalar        → OK
value shape (3,), constant shape (3,)    → OK
value shape (1,), constant shape (3,)    → ERROR

Binary operations with value2 follow standard backend broadcasting rules (NumPy/CuPy).

As an exception from standard broadcasting rule, if value2 has a shorter first dimension than value1, then the binary operation will only be applied to the first elements of value1, while the rest will left untouched.

Constraints

• Only one binary operation flag can be active at a time.

• value2 must be provided when a binary operation or concatenation is used.

• value2_remap cannot be used together with concat.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Base Slicer

class specula.processing_objects.base_slicer.BaseSlicer(indices=None, slice_args=None, target_device_idx=None, precision=None)

Bases: BaseProcessingObj

Base Slicer processing object. Extracts a subset of values from a BaseValue based on an index, list of indices, or a slice.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Base Sprint Estimator

Base SPRINT Estimator class with common demodulation and iteration logic. Specific WFS implementations should inherit from this class.

class specula.processing_objects.base_sprint_estimator.BaseSprintEstimator(simul_params: SimulParams, dm: DM, slopec: Slopec, source: Source, wfs: BaseProcessingObj, modes_index: list, carrier_frequencies: list, pupil_mask: Pupilstop = None, n_params: int = 4, estimation_dt: float = 10.0, max_iterations: int = 10, convergence_threshold: float = 0.001, initial_misreg: list = None, apply_absolute_slopes: bool = False, integration_gain: float = 0.5, forgetting_factor: float = 1.0, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Base SPRINT (System Parameters Recurrent Invasive Tracking) Estimator. This class implements the core logic for online estimation of WFS-DM mis-registration parameters using slope demodulation and iterative refinement.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)	Collect slopes for demodulation
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Initialize slopes size and extract parameters
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main SPRINT estimation logic

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Online calibration of WFS-DM mis-registration parameters using: 1. Slope demodulation to extract measured interaction matrix 2. WFS-specific sensitivity matrix computation (implemented in subclasses) 3. Iterative parameter refinement with optional integration/forgetting

Based on: Heritier+ 2021, MNRAS “SPRINT: a fast and least-cost

online calibration strategy for adaptive optics”

This base class handles: - Slope collection and demodulation - Iterative estimation loop - Integration with gain and forgetting factor - Input/output management

Subclasses must implement: - _compute_nominal_im(): Compute IM with current misreg parameters - _compute_sensitivity_matrices(): Compute sensitivity matrices - _validate_wfs(): Check WFS compatibility

Parameters:

• simul_params (SimulParams) – Simulation parameters

• dm (DM) – Deformable mirror object

• slopec (Slopec) – Slope computer object

• source (Source) – Guide star source object

• wfs (BaseProcessingObj) – WFS object (specific type depends on subclass)

• modes_index (list [1]) – List of mode indices to estimate

• carrier_frequencies (list [Hz]) – Carrier frequencies for each mode [Hz]

• estimation_dt (float [s]) – Time interval between estimations [seconds]

• max_iterations (int [1]) – Maximum iterations per estimation cycle

• convergence_threshold (float [1]) – Relative error threshold for convergence

• initial_misreg (list or None [1]) – Initial mis-registration [shift_x, shift_y, rot, magn(, magn_x, magn_y)]

• apply_absolute_slopes (bool) – Use absolute value of slopes

• enable_wpup_magn_xy (bool) – Enable separate X/Y magnification parameters

• integration_gain (float [1]) – Gain for parameter updates (0 < gain <= 1)

• forgetting_factor (float or None [1]) – Forgetting factor for integration (0 < factor <= 1, 1 = no forgetting)

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

• Inputs

• ------

• in_slopes (Slopes) – Current WFS slopes (modulated by pushpull_generator)

• Outputs

• -------

• out_intmat (Intmat) – Estimated interaction matrix

• out_misreg_params (BaseValue) – Estimated mis-registration parameters

• out_convergence_error (BaseValue) – Current relative error

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)	Collect slopes for demodulation
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Initialize slopes size and extract parameters
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main SPRINT estimation logic

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

Collect slopes for demodulation

setup()

Initialize slopes size and extract parameters

trigger_code()

Main SPRINT estimation logic

Ccd

class specula.processing_objects.ccd.CCD(simul_params: SimulParams, size: list, dt: float, bandw: float, binning: int = 1, photon_noise: bool = False, readout_noise: bool = False, excess_noise: bool = False, darkcurrent_noise: bool = False, background_noise: bool = False, cic_noise: bool = False, cte_noise: bool = False, readout_level: float = 0.0, darkcurrent_level: float = 0.0, background_level: float = 0.0, cic_level: float = 0, cte_mat=None, quantum_eff: float = 1.0, pixelGains=None, photon_seed: int = 1, readout_seed: int = 2, excess_seed: int = 3, excess_delta: float = 1.0, start_time: int = 0, ADU_gain: float = None, ADU_bias: int = 400, emccd_gain: int = None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Detector processing object simulating a CCD camera from intensity field. It integrates the input intensity over a given time (dt) and applies various noise sources to simulate a realistic CCD image.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
apply_binning
apply_noise
apply_qe
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters object reference.

• size (int list [pixels]) – Size of the CCD in pixels [nx, ny].

• dt (float [s]) – Integration time in seconds.

• bandw (float [1]) – Optical bandwidth in nm.

• binning (int [1], optional) – Pixel binning factor (default is 1, no binning).

• photon_noise (bool) – Whether to apply photon noise (Poisson noise) (default is False).

• readout_noise (bool) – Whether to apply readout noise (default is False).

• excess_noise (bool) – Whether to apply excess noise (default is False).

• darkcurrent_noise (bool) – Whether to apply dark current noise (default is False).

• background_noise (bool) – Whether to apply background noise (default is False).

• cic_noise (bool) – Whether to apply clock-induced charge noise (default is False).

• cte_noise (bool) – Whether to apply charge transfer efficiency noise (default is False).

• readout_level (float [e-/pixel], optional) – Readout noise level in electrons (default is 0.0).

• darkcurrent_level (float [1], optional) – Dark current level in electrons per pixel (default is 0.0).

• background_level (float [1], optional) – Background light level in electrons per pixel (default is 0.0).

• cic_level (float [1], optional) – Clock-induced charge level in electrons per pixel (default is 0).

• cte_mat (array [1], optional) – Charge transfer efficiency matrix (default is None).

• quantum_eff (float [1], optional) – Quantum efficiency (default is 1.0). This is typically use to account for overall throughput.

• pixelGains (array [1], optional) – Pixel gain variations (default is None).

• photon_seed (int [1], optional) – Random seed for photon noise (default is 1).

• readout_seed (int [1], optional) – Random seed for readout noise (default is 2).

• excess_seed (int [1], optional) – Random seed for excess noise (default is 3).

• excess_delta (float [1], optional) – Excess noise factor (default is 1.0). The excess noise factor is ENF = sqrt(2 - 1/excess_delta)

• start_time (int [s], optional) – Time to start the CCD integration (default is 0).

• ADU_gain (float [1], optional) – Analog-to-digital unit gain (default is None, which sets a default value based on excess noise).

• ADU_bias (int [1], optional) – Analog-to-digital unit bias level (default is 400).

• emccd_gain (int [1], optional) – Electron-multiplying CCD gain (default is None, which sets a default value based on excess noise).

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
apply_binning
apply_noise
apply_qe
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

apply_binning()

apply_noise()

apply_qe()

classmethod input_names()

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.ccd.clamp_generic(x, c, y, xp)

Ciao Ciao Sensor

class specula.processing_objects.ciao_ciao_sensor.CiaoCiaoSensor(wavelengthInNm: float, number_px: int, diffRotAngleInDeg: float = 180.0, tiltInArcsec=(0.0, 0.0), rotAnglePhInDeg: float = 0.0, xShiftPhInPixel: float = 0.0, yShiftPhInPixel: float = 0.0, magnification: float = 1.0, xShiftDiffPhInPixel: float = 0.0, yShiftDiffPhInPixel: float = 0.0, magnificationDiff: float = 1.0, channel_flux: float = 0.5, normalize_flux: bool = True, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Ciao-Ciao sensor (rotating shearing interferometer) processing object. The object duplicates the input electric field, rotates one copy, applies a user-defined tip/tilt to the rotated copy, then coherently sums the two complex fields and outputs the resulting intensity.

Parameters:

• wavelengthInNm (float [nm]) – Working wavelength in nanometers.

• number_px (int [pixels], optional) – Output side in pixels. If None, output has the same side as input EF. Default is None.

• diffRotAngleInDeg (float [deg], optional) – Differential rotation angle in degrees applied to the second branch. Default is 180.0.

• tiltInArcsec (tuple[float, float] | float [arcsec], optional) – User-defined tilt (x, y) in arcseconds applied to the rotated branch. If a scalar is provided, it is interpreted as x tilt and y=0. Default is (0.0, 0.0).

• rotAnglePhInDeg (float [deg], optional) – Rotation angle in degrees applied to the input branch. Default is 0.0.

• xShiftPhInPixel (float [pixels], optional) – X shift in pixels applied to the input branch. Default is 0.0.

• yShiftPhInPixel (float [pixels], optional) – Y shift in pixels applied to the input branch. Default is 0.0.

• magnification (float [1], optional) – Magnification applied to the input branch. Default is 1.0.

• xShiftDiffPhInPixel (float [pixels], optional) – Additional differential X shift in pixels applied only to the second branch. Default is 0.0.

• yShiftDiffPhInPixel (float [pixels], optional) – Additional differential Y shift in pixels applied only to the second branch. Default is 0.0.

• magnificationDiff (float [1], optional) – Additional differential magnification applied only to the second branch. Default is 1.0.

• channel_flux (float [1], optional) – Relative flux of the input branch in [0, 1]. The rotated branch uses (1 - channel_flux). Default is 0.5 (balanced channels).

• normalize_flux (bool) – If True, normalize output intensity to input photons S0 * masked_area. Default is True.

• target_device_idx (int [1], optional) – Target device index for GPU processing. Default is None.

• precision (int [1], optional) – Numerical precision (e.g., 32 or 64). Default is None.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.ciao_ciao_sensor.abs2(u_fp, out, xp)

Ciao Ciao Slopec

class specula.processing_objects.ciao_ciao_slopec.CiaoCiaoSlopec(wavelength_in_nm: float, window_x_in_pix: float, window_y_in_pix: float, window_sigma_in_pix: float, pupil_mask: Pupilstop, diffRotAngleInDeg: float = 0.0, unwrap: bool = False, sn: Slopes = None, target_device_idx: int = None, precision: int = None, **kwargs)

Bases: Slopec

Slope computer for the CiaoCiao WFS processing object.

Extracts the phase from an interferogram using the Fourier method: 1. Computes the FFT of the interferogram. 2. Isolates the carrier sideband using a Top-Flat Gaussian window. 3. Shifts the sideband to the center. 4. Computes the inverse FFT. 5. Extracts the phase (arctan2) and (optionally) unwraps it. 6. Converts the phase to OPD. 7. Exports the OPD map as a flattened output vector.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• wavelength_in_nm (float [nm]) – Working wavelength (e.g., 2200 for K band).

• window_x_in_pix (float [pixels]) – Coordinates of the sideband center in the FFT.

• window_y_in_pix (float [pixels]) – Coordinates of the sideband center in the FFT.

• window_sigma_in_pix (float [pixels]) – Width of the filtering window (Top Flat Gaussian).

• pupil_mask (Pupilstop) – Pupil mask defining the valid area. Its .A amplitude array is used. The effective mask is the intersection of this mask with a copy rotated by diffRotAngleInDeg, mirroring the overlap region seen by the CiaoCiao interferometer.

• diffRotAngleInDeg (float [deg], optional) – Rotation angle in degrees applied to one branch of the interferometer (same value as diffRotAngleInDeg in CiaoCiaoSensor). The effective pupil mask is mask & rotate(mask, diffRotAngleInDeg). Default is 0.0 (no rotation applied, mask used as-is).

• unwrap (bool, optional) – If True, performs 2D phase unwrapping using skimage (runs on CPU). Default is False.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

nslopes()

nsubaps()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Close Gain Optimizer

class specula.processing_objects.close_gain_optimizer.CloseGainOptimizer(nmodes: int, dt: float = 3, initial_gain: float = 0.5, p: float = 0.3, r: float = -0.1, q_plus: float = 0.01, q_minus_ratio: float = 5.0, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

CLOSE (Correlation-Locked Optimization StratEgy) gain optimizer processing object.

Implements a self-regulating tracker for modal integrator based AO loops, updating modal gains in real-time based on the temporal auto-correlation of modal measurements. Implements the correlation-locking approach: see Equations (3) and (4) in “CLOSE: a self-regulating, best-performance tracker for modal integrator based AO loops”, Deo et al. (2019).

Parameters:

• nmodes (int [1]) – Number of modes to optimize. Defines the dimensionality of the gain vector and the size of the modal measurement vector.

• initial_gain (float [1], optional) – Initial value for all modal gains. Default: 0.5

• dt (float [1], optional) – Time-shift (in frames) at which correlation is evaluated. Should be 2xdelay + 1, where delay is the pure delay of the control (total delay = delay + 1 frame). Default is 3.0 (delay = 1.0).

• p (float [1], optional) – Low-pass filter coefficient for autocorrelation estimators (Equation 3). Should be in range (0, 1]. Default: 0.3.

• r (float [1], optional) – Target correlation ratio setpoint. Defines the desired normalized autocorrelation value at lag dt. Theoretical value should be 0.0. Default: -0.1

• q_plus (float [1], optional) – Tracking gain increase factor. Learning rate for positive correlation error (when correlation is above setpoint). Controls how aggressively gains increase during normal operation. Should be small (typically 1e-2 to 1e-1). Default: 1e-2

• q_minus_ratio (float [1], optional) – Ratio of q_minus to q_plus for aggressive correction. When correlation is below setpoint (indicating ringing/overshoot), gain adjustment uses q_minus = q_plus * q_minus_ratio. Typically > 1 for faster damping. Default: 5.0

• target_device_idx (int [1], optional) – Target device index for computation (e.g., GPU device number). If None, uses CPU or default device. Default: None

• precision (int [1], optional) – Numerical precision for computations (e.g., 32 for float32, 64 for float64). If None, uses default precision. Default: None

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Cur Wfs Slopec

class specula.processing_objects.cur_wfs_slopec.CurWfsSlopec(diameter: int, ccd_size: tuple, sn: Slopes = None, interleave: bool = False, target_device_idx: int = None, precision: int = None)

Bases: Slopec

Slope Computer for Curvature Wavefront Sensor processing object. Computes the normalized difference between intra-focal and extra-focal fluxes on a pixel-by-pixel basis using PupData indices.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

diameter: int [pixels]

Diameter of the pupil in pixels (used to define valid pupil indices).

ccd_size: tuple [pixels]

Size of the CCD in pixels (height, width).

sn: Slopes, optional

Slopes object for reference subtraction (if needed).

interleave: bool, optional

Whether to interleave slopes (not used in this implementation).

target_device_idxint [1], optional

Target device index for computation (CPU/GPU). Default is None (uses global setting).

precisionint [1], optional

Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

nslopes()

nsubaps()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Curvature Sensor

class specula.processing_objects.curvature_sensor.CurvatureSensor(wavelengthInNm: float, wanted_fov: float, pxscale: float, number_px: int, defocus_rms_nm: float, fov_ovs_coeff: float = 2.0, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Curvature Wavefront Sensor (CWFS) propagator processing object. This class applies a Zernike Focus aberration (defocus) to the input electric field and propagates it to generate intra-focal and extra-focal intensity images.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

wavelengthInNm: float [nm]

Wavelength of the light in nanometers.

wanted_fov: float [arcsec]

Desired field of view in arcseconds.

pxscale: float [arcsec/pixel]

Desired pixel scale in arcseconds per pixel at the output.

number_px: int [pixels]

Desired output resolution (number of pixels on one side of the square output image).

defocus_rms_nm: float [nm]

RMS of the defocus aberration in nanometers (controls the strength of the curvature).

fov_ovs_coefffloat [1], optional

Coefficient to determine the oversampling of the FoV. A value larger than 1 is recommended to avoid FFT wrapping effects. Default is 2.0.

target_device_idxint [1], optional

Target device index for computation (CPU/GPU). Default is None (uses global setting).

precisionint [1], optional

Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.curvature_sensor.abs2_cwfs(u_fp, out, xp)

Data Buffer

class specula.processing_objects.data_buffer.DataBuffer(buffer_size: int = 10)

Bases: BaseProcessingObj

Data buffering processing object. Accumulates data and outputs it every N steps.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Emit any remaining data in buffers
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
reset_buffers()	Clear all buffers and reset counter
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
emit_buffered_data
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
setOutputs
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Emit any remaining data in buffers
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
reset_buffers()	Clear all buffers and reset counter
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
emit_buffered_data
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
setOutputs
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

check_input_names()

Check that all input names declared in self.input_names are present in self.inputs

with the correct type (InputValue or InputList).

Supported declaration grammar for input names: - Exact names, e.g. in_ef - Placeholder patterns, e.g. in_sensor_{idx}

Notes

• Placeholder segments {...} are treated as wildcards.

  • In project classes, placeholder-style declarations are mandatory;

    do not use raw * declarations in input_names().

• Optional declarations are identified by descriptions ending with

  (optional).

• Exact-key matches take precedence over pattern matches.

check_output_names()

Check that all output names declared in self.output_names are present in self.outputs

Supported declaration grammar for output names: - Exact names, e.g. out_ef

• Placeholder patterns, e.g. out_modes_{sensor_idx}

  (ModalrecMultirate)

• Placeholder patterns, e.g. out_{source_name_}layer

  (AtmoRandomPhase)

Notes

• Placeholder segments {...} are treated as wildcards.

  • In project classes, placeholder-style declarations are mandatory;

    do not use raw * declarations in output_names().

• Exact-key matches take precedence over pattern matches.

emit_buffered_data()

finalize()

Emit any remaining data in buffers

classmethod input_names()

classmethod output_names()

reset_buffers()

Clear all buffers and reset counter

setOutputs()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Data Print

class specula.processing_objects.data_print.DataPrint(print_dt: float = 1.0, range_slice: tuple = None, prefix: str = '', format_str: str = '.4f', target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Data print processing object. Print data values to screen at regular intervals

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the data print object.

Parameters: print_dt (float) [s]: Time interval between prints in seconds range_slice (tuple [1], optional): Tuple to create slice object to select which values to print.

If None, prints all values. Examples: (0, 5), (None, None, 2)

prefix (str): Text to print before the values format_str (str): Format specification for floating point numbers

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

trigger()

Data Source

class specula.processing_objects.data_source.DataSource(outputs: list, store_dir: str, data_format: str = 'fits', global_precision: int = None)

Bases: BaseProcessingObj

Data source processing object. Loads data from files and outputs it based on the current time.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
loadFromFile
load_fits
load_pickle
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
size
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
loadFromFile
load_fits
load_pickle
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
size
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

check_output_names()

Check that all output names declared in self.output_names are present in self.outputs

Supported declaration grammar for output names: - Exact names, e.g. out_ef

• Placeholder patterns, e.g. out_modes_{sensor_idx}

  (ModalrecMultirate)

• Placeholder patterns, e.g. out_{source_name_}layer

  (AtmoRandomPhase)

Notes

• Placeholder segments {...} are treated as wildcards.

  • In project classes, placeholder-style declarations are mandatory;

    do not use raw * declarations in output_names().

• Exact-key matches take precedence over pattern matches.

classmethod input_names()

loadFromFile(name)

load_fits(name)

load_pickle(name)

classmethod output_names()

size(name, dimensions=False)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Data Store

class specula.processing_objects.data_store.DataStore(store_dir: str, split_size: int = 0, first_suffix: int = 0, data_format: str = 'fits', start_time: float = 0, create_tn: bool = True, downsample_factor: int = 1, downsample_factor_by_input: dict = None)

Bases: BaseProcessingObj

Data storage processing object. Stores input values over time, optionally downsampling them on a per-input basis, and saves them to disk at the end of the run.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
create_TN_folder
device_stream
init_logging
init_storage
input_names
monitorMem
output_names
printMemUsage
save
save_fits
save_params
save_pickle
seconds_to_t
send_remote_output
setParams
setReplayParams
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger
update_header_with_storage_metadata

Parameters:

• store_dir (str) – Base directory where data will be stored. A subdirectory with a timestamp will be created inside this directory to hold the data files.

• split_size (int [1], optional) – If > 0, creates a new subdirectory and saves one chunk every split_size trigger iterations after start_time. Default is 0 (no splitting, all data in one folder).

• first_suffix (int [1], optional) – Starting suffix for split folders. Default is 0.

• data_format (str) – Format for saved data files. Supported values are ‘fits’ and ‘pickle’. Default is ‘fits’.

• start_time (float [s], optional) – Time in seconds to wait before starting to store data. Default is 0 (store from the beginning).

• create_tn (bool) – If True, creates a timestamped subdirectory for storing data. Default is True.

• downsample_factor (int [1], optional) – Store one sample every N received samples for all inputs. The downsampling is sample-based and tracked independently for each input, so an input that updates less frequently is counted only when it produces a new sample. Default is 1 (store every sample).

• downsample_factor_by_input (dict [1], optional) – Per-input downsampling factors. Keys are the DataStore input names, values are integers >= 1. When using input_list, the key is the alias before the dash, e.g. 'comm' for 'comm-control.out_comm'. This option is mutually exclusive with downsample_factor != 1.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
create_TN_folder
device_stream
init_logging
init_storage
input_names
monitorMem
output_names
printMemUsage
save
save_fits
save_params
save_pickle
seconds_to_t
send_remote_output
setParams
setReplayParams
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger
update_header_with_storage_metadata

check_input_names()

Check that all input names declared in self.input_names are present in self.inputs

with the correct type (InputValue or InputList).

Supported declaration grammar for input names: - Exact names, e.g. in_ef - Placeholder patterns, e.g. in_sensor_{idx}

Notes

• Placeholder segments {...} are treated as wildcards.

  • In project classes, placeholder-style declarations are mandatory;

    do not use raw * declarations in input_names().

• Optional declarations are identified by descriptions ending with

  (optional).

• Exact-key matches take precedence over pattern matches.

create_TN_folder(suffix='')

finalize()

Override this method to perform any actions after the simulation is completed

init_storage()

classmethod input_names()

classmethod output_names()

save()

save_fits()

save_params()

save_pickle()

setParams(params)

setReplayParams(replay_params)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

update_header_with_storage_metadata(header, input_name)

Demodulator

class specula.processing_objects.demodulator.Demodulator(simul_params: SimulParams, mode_numbers: list, carrier_frequencies: list, demod_dt: float, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Demodulator processing object for modal amplitude estimation. Demodulates input signals using carrier frequencies and outputs scalar values representing modal amplitudes.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Display Server

class specula.processing_objects.display_server.DisplayServer(params_dict: dict, input_ref_getter: Callable, output_ref_getter: Callable, info_getter: Callable, host: str = '0.0.0.0', port: int = 0, mode: str = 'image')

Bases: BaseProcessingObj

Display server processing object. Copies data objects to a separate process using multiprocessing queues. In this instance, the separate process is a Flask web server, but this class could be easily made generic to support different kinds of export processes.

This object must not be run concurrently with any other in the simulation, because it can in some cases temporarily modify the data objects (removing references to the xp module to allow pickling) It has two modes of operation: ‘image’ and ‘data’. In ‘image’ mode, it renders and sends the images correspoinding to the displayed data objects. In ‘data’ mode, it sends the raw data to the client, which is responsible for rendering.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

This object must not be run concurrently with any other in the simulation, because it can in some cases temporarily modify the data objects (removing references to the xp module to allow pickling)

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

classmethod input_names()

classmethod output_names()

trigger()

specula.processing_objects.display_server.encode(fig)

Encode a PNG image for web display

specula.processing_objects.display_server.remove_xp_np(obj)

Temporarily remove any instance of xp and np modules The removed modules are put back when exiting the context manager.

Works recursively on object lists

Distributed Sh

class specula.processing_objects.distributed_sh.DistributedSH(wavelengthInNm: float, subap_wanted_fov: float, sensor_pxscale: float, subap_on_diameter: int, subap_npx: int, n_slices: int, squaremask: bool = True, fov_ovs_coeff: float = 0, xShiftPhInPixel: float = 0, yShiftPhInPixel: float = 0, rotAnglePhInDeg: float = 0, set_fov_res_to_turbpxsc: bool = False, laser_launch_tel: LaserLaunchTelescope = None, target_device_idx: int = None, precision: int = None)

Bases: SH

SH class that distributes work on multiple devices.

Internally, it manages a series of hidden SH objects each performing a section of the subaperture processing. In post_trigger(), all results are gathered into a single Intensity array.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
check_ready(t)	Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Skip the SH method for this object, but call the BaseProcessingObj one for housekeeping.
prepare_trigger(t)	Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger()	Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping.
trigger_code()	Nothing to do in the distributed SH.

addRemoteOutput
build_stream
capture_stream
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
check_ready(t)	Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Skip the SH method for this object, but call the BaseProcessingObj one for housekeeping.
prepare_trigger(t)	Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger()	Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping.
trigger_code()	Nothing to do in the distributed SH.

addRemoteOutput
build_stream
capture_stream
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds

check_ready(t)

Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping. Then call all sub-SHs

classmethod input_names()

classmethod output_names()

post_trigger()

Skip the SH method for this object, but call the BaseProcessingObj one for housekeeping. Then gather results from the sub-SH and perform the final normalization

prepare_trigger(t)

Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping. Then call all sub-SHs

setup()

Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping. Then set inputs on all sub-SHs

trigger()

Skip the SH method for this object, since we do not perform any calculation, but call the BaseProcessingObj one for housekeeping. Then call all sub-SHs

trigger_code()

Nothing to do in the distributed SH. The Sub-SH will run the regular SH implementation.

Dm

class specula.processing_objects.dm.DM(simul_params: SimulParams, height: float, ifunc: IFunc = None, m2c: M2C = None, type_str: str = None, nmodes: int = None, nzern: int = None, start_mode: int = None, idx_modes=None, npixels: int = None, obsratio: float = None, diaratio: float = None, pupilstop: Pupilstop = None, sign: int = -1, stroke=None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Deformable Mirror processing object. It receives a command vector as input and produces a Layer object representing the DM wavefront.

Attributes:

ifunc

ifunc_obj

Return the IFunc object (not just the array)

mask

type_str

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

• The output layer object contains a wavefront not a surface. Wavefront = 2 x surface (reflection).

• The DM wavefront deformation is represented as a phase screen in nanometers.

• Sign parameter is -1 by default to account for reflection in wave propagation.

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing pupil size, pixel pitch, etc.

• height (float [m]) – Height of the DM layer in meters (this is distance from the pupil).

• ifunc (IFunc) – Influence function object defining the DM actuator influence functions.

• m2c (M2C) – Mode-to-command matrix object for converting mode commands to actuator commands.

• type_str (str) – Type of influence function to use if ifunc is not provided.

• nmodes (int [1], optional) – Number of modes to consider if ifunc is not provided.

• nzern (int [1], optional) – Maximum Zernike radial order if ifunc is not provided. This is used from mixed Zernike KL bases (not implemented yet).

• start_mode (int [1], optional) – Starting mode index for the DM modes.

• idx_modes (list or array [1], optional) – Specific mode indices to use for the DM. If provided, start_mode and nmodes are ignored.

• npixels (int [pixels], optional) – Number of pixels for the DM layer. If None, defaults to pupil size.

• obsratio (float [1], optional) – Obscuration ratio for the influence function if ifunc is not provided.

• diaratio (float [1], optional) – Diagonal ratio for the influence function if ifunc is not provided.

• pupilstop (Pupilstop) – Pupilstop object defining the DM aperture.

• sign (int [1], optional) – Sign for the DM surface deformation, by default -1.

• stroke (float or list [nm], optional) – The maximum amplitude (in NANOMETERS) to which commands are clipped at. If a list is given, this is the maximum amplitude that can be applied per mode. Default is None (no clipping applied).

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Attributes:

ifunc

ifunc_obj

Return the IFunc object (not just the array)

mask

type_str

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

property ifunc

property ifunc_obj

Return the IFunc object (not just the array)

classmethod input_names()

property mask

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

property type_str

Double Roof Slopec

class specula.processing_objects.double_roof_slopec.DoubleRoofSlopec(pupdata: PupData, sn: Slopes = None, shlike: bool = False, norm_factor: float = None, thr_value: float = 0, slopes_from_intensity: bool = False, target_device_idx: int = None, precision: int = None, **kwargs)

Bases: PyrSlopec

Double roof slope computer processing object. A DoubleRoofSlopec is a standard pyramid slope computer, customized for the double-roof case.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

Dynamic Dark Calibrator

class specula.processing_objects.dynamic_dark_calibrator.DynamicDarkCalibrator(data_dir: str, nframes: int, overwrite: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Dynamic dark frame calibrator for pixel streams.

This processing object computes and applies a dark frame correction by averaging a configurable number of input frames. The resulting dark frame is subtracted from incoming pixel data in all subsequent loop iterations.

The calibration process is controlled via input triggers and can be dynamically reset, updated, saved, or loaded during runtime.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
save([filename])	Save dark frame data to disk as a FITS file
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Resize output darkframe to match input pixel dimensions and properties
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main calibration function

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• data_dir (str) – Directory where dark frames are saved to and loaded from. Usually set automatically by CalibManager.

• nframes (int [1]) – Number of frames to integrate when computing the dark frame. Must be greater than zero.

• overwrite (bool) – If True, overwrite existing files when saving dark frames. Default is False.

• target_device_idx (int [1], optional) – Target device index for computation (e.g., CPU/GPU selection).

• precision (int [1], optional) – Numerical precision for internal data.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
save([filename])	Save dark frame data to disk as a FITS file
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Resize output darkframe to match input pixel dimensions and properties
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main calibration function

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

save(filename=None)

Save dark frame data to disk as a FITS file

setup()

Resize output darkframe to match input pixel dimensions and properties

trigger_code()

Main calibration function

Dynamic Iir Filter

class specula.processing_objects.dynamic_iir_filter.DynamicIirFilter(iir_filter_data: IirFilterData, delay: float = 0, integration: bool = True, target_device_idx=None, precision=None)

Bases: IirFilter

Dynamic Infinite Impulse Response filter processing object. Same as standard IIR filter, with dynamic parameters.

Parameters:

• iir_filter_data (IirFilterData) – Filter coefficients (numerator and denominator)

• delay (float [1], optional) – Delay in frames to apply to the output (default: 0)

• integration (bool) – If False, disables feedback terms (converts IIR to FIR). This is done by masking the denominator coefficients while preserving the normalizing factor. (default: True)

• target_device_idx (int [1], optional) – Target device for computation (-1 for CPU, >=0 for GPU)

• precision (int [1], optional) – Numerical precision (0 for double, 1 for single)

Notes

When integration=False, the filter becomes purely feedforward (FIR), removing all feedback/memory from previous outputs while maintaining the gain characteristics defined by the numerator coefficients.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

Provides common functionality for:

• Delay buffer management

• Interpolation for fractional delays

• Gain modulation

• Synchronous (no-delay) outputs for POLC

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

Dynamic Integrator

class specula.processing_objects.dynamic_integrator.DynamicIntegrator(int_gain: float, ff: list = None, n_modes: int = None, delay: float = 0, integration: bool = True, target_device_idx: int = None, precision: int = None)

Bases: Integrator

Dynamic integrator with runtime-adjustable gain and reset capability.

This class extends Integrator by allowing dynamic updates of the integration gain and providing a reset mechanism for internal filter states during runtime.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• int_gain (float [1]) – Initial integrator gain.

• ff (list [1], optional) – Feedforward coefficients for the IIR filter.

• n_modes (int [1], optional) – Number of modes for modal integration.

• delay (float [1], optional) – Delay applied to the integrator (in simulation time units). Default is 0.

• integration (bool) – If True, enable integration behavior. Default is True.

• target_device_idx (int [1], optional) – Target device index for computation (e.g., CPU/GPU).

• precision (int [1], optional) – Numerical precision for internal data (0 for double, 1 for single).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

Dynamic Pyr Pupdata Calibrator

class specula.processing_objects.dynamic_pyr_pupdata_calibrator.DynamicPyrPupdataCalibrator(data_dir: str, dt: float = None, thr1: float = 0.1, thr2: float = 0.25, obs_thr: float = 0.8, slopes_from_intensity: bool = False, output_tag: str = None, auto_detect_obstruction: bool = True, min_obstruction_ratio: float = 0.05, display_debug: bool = False, overwrite: bool = False, save_on_exit: bool = True, target_device_idx: int = None, precision: int = None)

Bases: PyrPupdataCalibrator

Dynamic Pyramid Pupdata Calibrator. Pyramid pupil data calibrator with interactive control.

This class extends PyrPupdataCalibrator by adding support for dynamic parameter updates and on-demand saving via input triggers. Calibration parameters such as time step and thresholds can be modified during runtime without restarting the processing pipeline.

A failed pupil measurement will not stop the simulation, but will be instead signalled using the “status_string” member of the “out_params” dictionary, as well by the fact that the output pudata will not be refreshed. Whenever a pupil measurement is successful, status_string will be set to “OK”.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main calibration function

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• data_dir (str) – Directory where calibration data is stored.

• dt (float [s], optional) – Time step for processing (in seconds).

• thr1 (float [1], optional) – First threshold used in pupil processing. Default is 0.1.

• thr2 (float [1], optional) – Second threshold used in pupil processing. Default is 0.25.

• obs_thr (float [1], optional) – Threshold for obstruction detection. Default is 0.8.

• slopes_from_intensity (bool) – If True, compute indices suitable for calculation of slopes from intensity. Default is False.

• output_tag (str) – Tag used to label output files.

• auto_detect_obstruction (bool) – Enable automatic obstruction detection. Default is True.

• min_obstruction_ratio (float [1], optional) – Minimum obstruction ratio to consider. Default is 0.05.

• display_debug (bool) – If True, enable debug visualization. Default is False.

• overwrite (bool) – If True, overwrite existing files. Default is False.

• save_on_exit (bool) – If True, automatically save data on exit. Default is True.

• target_device_idx (int [1], optional) – Target device index for computation.

• precision (int [1], optional) – Numerical precision for internal data (0 for double, 1 for single).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main calibration function

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Main calibration function

Electric Field Combinator

class specula.processing_objects.electric_field_combinator.ElectricFieldCombinator(target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Combines two input electric fields.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger()

Electric Field Reflection

class specula.processing_objects.electric_field_reflection.ElectricFieldReflection(target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Reflects an input electric field (changes the sign of the phase).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger()

Ext Source Pyramid

class specula.processing_objects.ext_source_pyramid.ExtSourcePyramid(simul_params: SimulParams, wavelengthInNm: float, fov: float, pup_diam: int, output_resolution: int, fov_errinf: float = 0.5, fov_errsup: float = 2, pup_dist: int = None, pup_margin: int = 2, fft_res: float = 3.0, fp_obs: float = None, pup_shifts=(0.0, 0.0), pyr_tlt_coeff: float = None, pyr_edge_def_ld: float = 0.0, pyr_tip_def_ld: float = 0.0, pyr_tip_maya_ld: float = 0.0, min_pup_dist: float = None, rotAnglePhInDeg: float = 0.0, xShiftPhInPixel: float = 0.0, yShiftPhInPixel: float = 0.0, max_batch_size: int = 128, max_flux_ratio_thr: float = 0.001, cuda_stream_enable: bool = True, target_device_idx: int = None, precision: int = None)

Bases: ModulatedPyramid

Pyramid processing object for extended sources. Extends the ModulatedPyramid processing object to handle extended sources.

Extended sources are handlded by computing pupil phases on-the-fly for each source point, reducing memory usage compared to pre-computing and storing all tip-tilt exponentials.

The extended source is represented by a set of point sources, each with tip, tilt, focus coefficients and flux. Processing is done in batches to manage GPU memory efficiently.

Methods

cache_ttexp()	Cache tip/tilt exponentials for modulation or extended source
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_tlt_f(p, c)	Generate tilt factor for pyramid de-rotation
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
calc_pyr_geometry
capture_stream
check_ready
device_stream
get_fp_mask
get_modulation_tilts
get_pyr_tlt
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

cache_ttexp()	Cache tip/tilt exponentials for modulation or extended source
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_tlt_f(p, c)	Generate tilt factor for pyramid de-rotation
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
calc_pyr_geometry
capture_stream
check_ready
device_stream
get_fp_mask
get_modulation_tilts
get_pyr_tlt
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

cache_ttexp()

Cache tip/tilt exponentials for modulation or extended source

classmethod input_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.ext_source_pyramid.pyr1_abs2(v, norm, ffv, xp)

specula.processing_objects.ext_source_pyramid.pyr1_fused(u_fp, ffv, fpsf, masked_exp, xp)

Extended Source

class specula.processing_objects.extended_source.ExtendedSource(simul_params: SimulParams, wavelengthInNm: float, source_type: str, sampling_lambda_over_d: float = 1.0, size_obj: float | None = None, sampling_type: str = 'CARTESIAN', layer_height: List[float] | None = None, intensity_profile: List[float] | None = None, focus_height: float | None = None, tt_profile: ndarray | None = None, n_rings: int | None = None, flux_threshold: float = 0.0, initial_psf: ndarray | None = None, pixel_scale_psf: float | None = None, crop_psf: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Extended source processing object. Computes extended sources (list of 3D points) for pyramid wavefront sensing.

The output “coeff” is constant, unless source_type is set to ‘FROM_PSF’, in which case it can be updated by providing a new PSF through the ‘psf’ input.

Parameters:

• simul_params (SimulParams) – Simulation parameters.

• wavelengthInNm (float) – Wavelength in nanometers.

• source_type (str) – Type of source (‘POINT_SOURCE’, ‘TOPHAT’, ‘GAUSS’, ‘FROM_PSF’).

• sampling_lambda_over_d (float) – Sampling factor in units of λ/D. Larger values mean less points.

• size_obj (Optional[float]) – Size of the object in arcseconds. Required for ‘TOPHAT’ and ‘GAUSS’ sources.

• sampling_type (str) – Sampling type (‘CARTESIAN’, ‘POLAR’, ‘RINGS’).

• layer_height (Optional[List[float]]) – Heights of layers in meters. Used for 3D sources (sodium beacon).

• intensity_profile (Optional[List[float]]) – Intensity profile for each layer. Used for 3D sources (sodium beacon).

• focus_height (Optional[float]) – Height of the focus in meters. Used for 3D sources (sodium beacon).

• tt_profile (Optional[np.ndarray]) – Tip/tilt profile for each layer. Used for 3D sources (sodium beacon).

• n_rings (Optional[int]) – Number of rings for ‘RINGS’ sampling. Default is 0.

• flux_threshold (float) – Threshold for flux. Points with flux below this value are discarded.

• initial_psf (Optional[np.ndarray]) – PSF array for ‘FROM_PSF’ source type to be used for initialization.

• pixel_scale_psf (Optional[float]) – Pixel scale of the PSF in arcseconds. Required for ‘FROM_PSF’ source type.

• crop_psf (bool) – Whether to crop the PSF to relevant parts defined by initial_psf size. Default is False.

• target_device_idx (int) – Index of the target device for computation. 0 is first GPU, -1 is CPU.

• precision (int) – Precision for computation (e.g., 32 or 64 bits). 1 is single precision, 0 is double precision.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
compute()	Main computation method
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
plot_source()	Plot the extended source distribution
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger()	Update PSF if new data is available and recompute if needed
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
compute()	Main computation method
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
plot_source()	Plot the extended source distribution
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger()	Update PSF if new data is available and recompute if needed
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds

compute()

Main computation method

classmethod input_names()

classmethod output_names()

plot_source()

Plot the extended source distribution

trigger()

Update PSF if new data is available and recompute if needed

Focal Plane Filter

class specula.processing_objects.focal_plane_filter.FocalPlaneFilter(simul_params: SimulParams, wavelengthInNm: float, fov: float, fov_errinf: float = 0.1, fov_errsup: float = 10, fft_res: float = 3.0, fp_obs: float = 0.0, target_device_idx: int = None, precision: int = None)

Bases: Coronagraph

Basic focal plane filter processing object. Consists of a round pupil with a given diameter and optional obstruction in the center.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters containing pixel_pupil and pixel_pitch

• wavelengthInNm (float) – Wavelength in nm

• fov (float) – Desired field of view in lambda/D on focal plane

• fov_errinf (float, optional) – Relative error allowed on the inner part of the FOV (default: 0.1)

• fov_errsup (float, optional) – Relative error allowed on the outer part of the FOV (default: 10)

• fft_res (float, optional) – Desired resolution in the focal plane in pixels per lambda/D (default: 3.0)

• center_on_pixel (bool, optional) – Whether to center the focal plane mask on a single pixel (True) or at the intersection of 4 pixels (False). This affects the phase shift applied to the electric field (default: True)

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

make_focal_plane_mask()

Override this method to create the desired focal plane (complex) mask

make_pupil_plane_mask()

Override this method to create the desired pupil plane (complex) mask

classmethod output_names()

Four Quadrant Coronagraph

class specula.processing_objects.four_quadrant_coronagraph.FourQuadrantCoronagraph(simul_params: SimulParams, wavelengthInNm: float, innerStopAsRatioOfPupil: float = 0.0, outerStopAsRatioOfPupil: float = 1.0, phase_delay: float = 3.141592653589793, fft_res: float = 3.0, target_device_idx: int = None, precision: int = None)

Bases: Coronagraph

Focal plane mask processing object. Generates a mask with four quadrants.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Make a quadrant mask, where 2 opposite quadrants apply a pi phase delay
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters containing pixel_pupil and pixel_pitch

• wavelengthInNm (float) – Wavelength in nm

• fov (float) – Desired field of view in lambda/D on focal plane

• fov_errinf (float, optional) – Relative error allowed on the inner part of the FOV (default: 0.1)

• fov_errsup (float, optional) – Relative error allowed on the outer part of the FOV (default: 10)

• fft_res (float, optional) – Desired resolution in the focal plane in pixels per lambda/D (default: 3.0)

• center_on_pixel (bool, optional) – Whether to center the focal plane mask on a single pixel (True) or at the intersection of 4 pixels (False). This affects the phase shift applied to the electric field (default: True)

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Make a quadrant mask, where 2 opposite quadrants apply a pi phase delay
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

make_focal_plane_mask()

Make a quadrant mask, where 2 opposite quadrants apply a pi phase delay

make_pupil_plane_mask()

Override this method to create the desired pupil plane (complex) mask

classmethod output_names()

Gain Optimizer

class specula.processing_objects.gain_optimizer.GainOptimizer(simul_params: SimulParams, iir_filter_data: IirFilterData, opt_dt: float = 1.0, delay: float = 2.0, max_gain_factor: float = 0.95, safety_factor: float = 0.9, max_inc: float = 0.5, limit_inc: bool = True, ngains: int = 20, running_mean: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Gain optimizer processing object. Implements IIR filters based on modal gain optimization (GENDRON 1994).

This class optimizes the gains of an IIR filter by minimizing the residual variance in the closed-loop system using pseudo open-loop measurements.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Ideal Derivative Sensor

class specula.processing_objects.ideal_derivative_sensor.IdealDerivativeSensor(simul_params: SimulParams, subapdata: SubapData, fov: float, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Ideal derivative sensor processing object. Computes slopes from wavefront derivatives.

This sensor extrapolates the phase outside the pupil mask using linear extrapolation, then computes X and Y derivatives to generate slopes for each subaperture.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Setup the sensor geometry and caching.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main processing: extrapolate phase and compute slopes.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the ideal derivative sensor.

Parameters:

• subapdata – Subaperture data object defining the geometry

• pixel_pitch – Pixel pitch in meters

• fov – Field of view in arcseconds (radius). This is used to get the same scale factor of a SH sensor

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Setup the sensor geometry and caching.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main processing: extrapolate phase and compute slopes.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

setup()

Setup the sensor geometry and caching.

trigger_code()

Main processing: extrapolate phase and compute slopes.

Iir Filter

class specula.processing_objects.iir_filter.IirFilter(iir_filter_data: IirFilterData, delay: float = 0, integration: bool = True, target_device_idx=None, precision=None)

Bases: BaseFilter

Infinite Impulse Response filter processing object. Implements IIR filtering with optional integration control.

Parameters:

• iir_filter_data (IirFilterData) – Filter coefficients (numerator and denominator)

• delay (float [1], optional) – Delay in frames to apply to the output (default: 0)

• integration (bool) – If False, disables feedback terms (converts IIR to FIR). This is done by masking the denominator coefficients while preserving the normalizing factor. (default: True)

• target_device_idx (int [1], optional) – Target device for computation (-1 for CPU, >=0 for GPU)

• precision (int [1], optional) – Numerical precision (0 for double, 1 for single)

Notes

When integration=False, the filter becomes purely feedforward (FIR), removing all feedback/memory from previous outputs while maintaining the gain characteristics defined by the numerator coefficients.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

Provides common functionality for:

• Delay buffer management

• Interpolation for fractional delays

• Gain modulation

• Synchronous (no-delay) outputs for POLC

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

reset_states()

Reset IIR internal states.

trigger_code()

IIR filter computation.

Im Calibrator

class specula.processing_objects.im_calibrator.ImCalibrator(nmodes: int, data_dir: str, im_tag: str = '', first_mode: int = 0, overwrite: bool = False, pupilstop: Pupilstop = None, dm: DM = None, source: Source = None, sensor: BaseProcessingObj = None, slopec: BaseProcessingObj = None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Interaction matrix calibrator processing object.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
generate_im_tag(pupilstop, source, dm, ...)	Generate automatic im_tag based on configuration parameters.
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
generate_im_tag(pupilstop, source, dm, ...)	Generate automatic im_tag based on configuration parameters.
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

static generate_im_tag(pupilstop, source, dm, sensor, slopec, nmodes, first_mode=0)

Generate automatic im_tag based on configuration parameters.

classmethod input_names()

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Im Sh Synim Generator

Interaction Matrix Generator for Shack-Hartmann WFS using SynIM.

This processing object computes a full interaction matrix given mis-registration parameters, and optionally computes the corresponding reconstruction matrix. Can be connected to SPRINT estimator output to generate corrected IM and RM.

class specula.processing_objects.im_sh_synim_generator.ImShSynimGenerator(simul_params: SimulParams, dm: DM, slopec: ShSlopec, source: Source, wfs: SH, compute_rec: bool = True, rec_nmodes: int = None, mmse: bool = False, r0: float = 0.15, L0: float = 25.0, noise_cov: float | ndarray | list = None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Interaction Matrix and Reconstruction Matrix Generator processing object for Shack-Hartmann WFS.

Computes interaction matrix and reconstruction matrix with specified mis-registration parameters using SynIM geometric model.

Can be connected to SPRINT estimator to automatically generate corrected IM and RM when new mis-registration parameters are estimated.

Parameters:

• simul_params (SimulParams) – Simulation parameters

• dm (DM) – Deformable mirror object

• slopec (ShSlopec) – Shack-Hartmann slope computer

• source (Source) – Guide star source

• wfs (SH) – Shack-Hartmann WFS object

• compute_rec (bool) – Compute reconstruction matrix (default: True)

• rec_nmodes (int or None [1]) – Number of modes for reconstruction (None = same as IM)

• mmse (bool) – Use MMSE reconstruction instead of pseudo-inverse (default: False)

• r0 (float [m]) – Fried parameter for MMSE [m] (default: 0.15)

• L0 (float [m]) – Outer scale for MMSE [m] (default: 25.0)

• noise_cov (float, ndarray, list, or None [1]) – Noise covariance for MMSE (required if mmse=True)

• target_device_idx (int or None [1]) – GPU device index

• precision (int or None [1]) – Numerical precision

• Inputs

• ------

• in_misreg_params (BaseValue, optional) – Mis-registration parameters [shift_x, shift_y, rotation, magnification] If not connected, uses zeros (perfect registration)

• Outputs

• -------

• out_intmat (Intmat) – Generated interaction matrix

• out_recmat (Recmat) – Generated reconstruction matrix (if compute_rec=True)

Examples

# Basic usage with pseudo-inverse >>> im_gen = ImShSynimGenerator( … simul_params=simul_params, … dm=dm, … slopec=slopec, … source=source, … wfs=wfs, … compute_rec=True … )

# With MMSE reconstruction >>> im_gen = ImShSynimGenerator( … simul_params=simul_params, … dm=dm, … slopec=slopec, … source=source, … wfs=wfs, … compute_rec=True, … mmse=True, … r0=0.15, … L0=25.0, … noise_cov=0.1 … )

# Connected to SPRINT >>> sprint = SprintShSynim(…) >>> im_gen = ImShSynimGenerator(…) >>> im_gen.inputs[‘in_misreg_params’].set(sprint.outputs[‘out_misreg_params’])

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
generate_im(misreg_params)	Generate interaction matrix with given mis-registration.
generate_rec()	Generate reconstruction matrix from current interaction matrix.
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Initialize and extract parameters
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Generate IM and optionally REC when input changes or on demand

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
generate_im(misreg_params)	Generate interaction matrix with given mis-registration.
generate_rec()	Generate reconstruction matrix from current interaction matrix.
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Initialize and extract parameters
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Generate IM and optionally REC when input changes or on demand

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

generate_im(misreg_params)

Generate interaction matrix with given mis-registration.

Parameters:

misreg_params (array_like) –

Mis-registration parameters: - If length 4: [shift_x, shift_y, rotation, magnification] - If length 6: [shift_x, shift_y, rotation, mag_global,

anamorphosis_90, anamorphosis_45]

Returns:

im – Interaction matrix

Return type:

ndarray, shape (nslopes, nmodes)

generate_rec()

Generate reconstruction matrix from current interaction matrix.

Returns:

rec – Reconstruction matrix

Return type:

Recmat

classmethod input_names()

classmethod output_names()

setup()

Initialize and extract parameters

trigger_code()

Generate IM and optionally REC when input changes or on demand

Integrator

class specula.processing_objects.integrator.Integrator(int_gain: list, ff: list = None, n_modes: list = None, delay: float = 0, integration: bool = True, target_device_idx: int = None, precision: int = None)

Bases: IirFilter

Integrator processing object. Specialized IIR filter with integration.

This class is a specialized version of the IirFilter class, designed to handle integration operations with specific gain and forgetting factor settings.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

Lift

class specula.processing_objects.lift.Lift(simul_params: SimulParams, nPistons: int, nZern: int, wavelengthInNm: float, pix_scale: float, cropped_size: int, ifunc: IFunc, ref_zern_amp, npix_side: int = None, ron: float = 0.0, n_iter: int = 20, fft_res: int = 2, fix: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

LIFT algorithm processing object. Implements the LIFT algorithm for phase estimation from a focal plane image, as described in Meimon et al. 2010.

Methods

calc_geometry(phase_sampling, pixel_pitch, ...)	Calculate WFS geometry
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
computeNoiseCovarianceDiag(image)	Compute noise covariance matrix.
crop_or_enlarge_around_peak(in_array, ...[, ...])	Function to crop a PSF frame or enlarge it around the peak, depending on whether it is larger or smaller than the desired width.
finalize()	Override this method to perform any actions after the simulation is completed
focalPlaneImageLIFT(phase[, set_flux])	Backward compatibility, called from example/test
get_all_inputs()	Perform get() on all inputs.
phaseFromCoeffs(coeffs)	Phase reconstruction from modal coefficients
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

IK_prime
abs2
addRemoteOutput
applyReconstructor
build_stream
calcCenter
calcCroppedFlux
calcDerivatives
capture_stream
check_ready
complexField
computeCoG
computeReconstructor
crop
device_stream
focalPlaneImageFromFFT
ft_ft2
getError
init_logging
input_names
monitorMem
output_names
phaseEstimation
phaseLIFT
printMemUsage
seconds_to_t
send_remote_output
setPsf
setRefTT
set_modalbase
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters object reference.

• nPistons (int [1]) – Number of piston modes in the modal base (see ifunc argument).

• nZern (int [1]) – Number of Zernike modes in the modal base (see ifunc argument).

• wavelengthInNm (float [nm]) – Wavelength in nanometers.

• pix_scale (float [arcsec/px]) – Pixel scale.

• npix_side (int [pixels]) – Number of pixels per side.

• cropped_size (int [pixels]) – Cropped size.

• ifunc (IFunc, optional) – Influence function data object. It must be coherent with nPistons and nZern modes, the first two zernike modes (if nZern>0) must be tip and tilt.

• ref_zern_amp (sequence [rad]) – Reference amplitudes for the Zernike block of the modal base, ordered exactly as in ifunc, i.e. starting from tip, tilt, defocus, and so on. Units are phase radians. It must have length nZern.

• n_iter (int [1], optional) – Number of iterations. Defaults to 20.

• fft_res (int [1], optional) – FFT resolution. Defaults to 2.

• fix (bool) – Fix flag. Defaults to False.

• target_device_idx (int [1], optional) – Target device index. Defaults to None.

• precision (int [1], optional) – Precision. Defaults to None.

Methods

calc_geometry(phase_sampling, pixel_pitch, ...)	Calculate WFS geometry
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
computeNoiseCovarianceDiag(image)	Compute noise covariance matrix.
crop_or_enlarge_around_peak(in_array, ...[, ...])	Function to crop a PSF frame or enlarge it around the peak, depending on whether it is larger or smaller than the desired width.
finalize()	Override this method to perform any actions after the simulation is completed
focalPlaneImageLIFT(phase[, set_flux])	Backward compatibility, called from example/test
get_all_inputs()	Perform get() on all inputs.
phaseFromCoeffs(coeffs)	Phase reconstruction from modal coefficients
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

IK_prime
abs2
addRemoteOutput
applyReconstructor
build_stream
calcCenter
calcCroppedFlux
calcDerivatives
capture_stream
check_ready
complexField
computeCoG
computeReconstructor
crop
device_stream
focalPlaneImageFromFFT
ft_ft2
getError
init_logging
input_names
monitorMem
output_names
phaseEstimation
phaseLIFT
printMemUsage
seconds_to_t
send_remote_output
setPsf
setRefTT
set_modalbase
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

IK_prime(index, Pd, conjPdTilde, center)

abs2(x)

applyReconstructor(P_ML, DeltaI)

calcCenter(frame)

calcCroppedFlux(frame, center)

calcDerivatives(complexField, complexFieldFFT, roi)

static calc_geometry(phase_sampling, pixel_pitch, wavelengthInNm, pix_scale, fft_res)

Calculate WFS geometry

complexField(phase)

computeCoG(frame, thFactor=0.05)

computeNoiseCovarianceDiag(image)

Compute noise covariance matrix. Only return the diagonal to avoid allocating a big matrix.

computeReconstructor(H, Rdiag)

crop(frame, center, side=None)

crop_or_enlarge_around_peak(in_array, desired_width, peak_index=None)

Function to crop a PSF frame or enlarge it around the peak, depending on whether it is larger or smaller than the desired width.

peak_index: tuple with the (r,c) integer coordinates of the

image center. If None, it will be found with np.argmax

finalize()

Override this method to perform any actions after the simulation is completed

focalPlaneImageFromFFT(complexFieldFFT, set_flux=None)

focalPlaneImageLIFT(phase, set_flux=None)

Backward compatibility, called from example/test

ft_ft2(x)

getError(DeltaI, Rinv)

classmethod input_names()

classmethod output_names()

phaseEstimation(psf_orig, relTol=0.001, absTol=0.001)

phaseFromCoeffs(coeffs)

Phase reconstruction from modal coefficients

phaseLIFT(p)

setPsf(psf)

setRefTT(center_x, center_y, image_size)

set_modalbase(modalbase, mask2d)

trigger()

class specula.processing_objects.lift.WFS_Settings(sampling_ratio, fft_sampling, fft_padding, fft_size, actual_fov, fft_res, bin_fact)

Bases: tuple

WFS settings

Contains the input parameters used to calculate the wfs internal array geometries.

Methods

count(value, /)	Return number of occurrences of value.
index(value[, start, stop])	Return first index of value.

Create new instance of WFS_Settings(sampling_ratio, fft_sampling, fft_padding, fft_size, actual_fov, fft_res, bin_fact)

Methods

count(value, /)	Return number of occurrences of value.
index(value[, start, stop])	Return first index of value.

actual_fov

Alias for field number 4

bin_fact

Alias for field number 6

fft_padding

Alias for field number 2

fft_res

Alias for field number 5

fft_sampling

Alias for field number 1

fft_size

Alias for field number 3

sampling_ratio

Alias for field number 0

Linear Combination

class specula.processing_objects.linear_combination.LinearCombination(simul_params: SimulParams, no_focus: bool = False, no_lift: bool = False, dm1: DM = None, dm3: DM = None, start_modes: list = [], plate_scale_idx: int = None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Linear combination processing objects. Combination of multiple input vectors, specialized for MORFEO-like systems

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Low Pass Filter

class specula.processing_objects.low_pass_filter.LowPassFilter(simul_params: SimulParams, cutoff_freq: float, amplif_fact: float = None, n_ord: int = None, delay: float = 0, target_device_idx: int = None, precision: int = None)

Bases: IirFilter

Low pass filter processing object. Specialization of the IirFilter class, implementing a low pass filter.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

Provides common functionality for:

• Delay buffer management

• Interpolation for fractional delays

• Gain modulation

• Synchronous (no-delay) outputs for POLC

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset IIR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	IIR filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

Lyot Coronagraph

class specula.processing_objects.lyot_coronagraph.LyotCoronagraph(simul_params: SimulParams, wavelengthInNm: float, iwaInLambdaOverD: float, owaInLambdaOverD: float = None, innerStopAsRatioOfPupil: float = 0.0, outerStopAsRatioOfPupil: float = 1.0, knife_edge: bool = False, fft_res: float = 3.0, target_device_idx: int = None, precision: int = None)

Bases: Coronagraph

Lyot coronograh processing object. Focal plane mask implementing a Lyot coronagraph

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters containing pixel_pupil and pixel_pitch

• wavelengthInNm (float) – Wavelength in nm

• fov (float) – Desired field of view in lambda/D on focal plane

• fov_errinf (float, optional) – Relative error allowed on the inner part of the FOV (default: 0.1)

• fov_errsup (float, optional) – Relative error allowed on the outer part of the FOV (default: 10)

• fft_res (float, optional) – Desired resolution in the focal plane in pixels per lambda/D (default: 3.0)

• center_on_pixel (bool, optional) – Whether to center the focal plane mask on a single pixel (True) or at the intersection of 4 pixels (False). This affects the phase shift applied to the electric field (default: True)

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

make_focal_plane_mask()

Override this method to create the desired focal plane (complex) mask

make_pupil_plane_mask()

Override this method to create the desired pupil plane (complex) mask

classmethod output_names()

Mirror Commands Combinator

class specula.processing_objects.mirror_commands_combinator.MirrorCommandsCombinator(k_vector, recmat: Recmat, dims_LO: list = [], dims_P: int = 1, dims_F: int = 1, out_dims: list = [], target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Mirror commands combinator processing object, Combines commands from multiple sources, specialized for MORFEO-like systems

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Modal Analysis

class specula.processing_objects.modal_analysis.ModalAnalysis(ifunc: IFunc = None, ifunc_inv: IFuncInv = None, type_str: str = None, npixels: int = None, obsratio: float = None, diaratio: float = None, pupilstop: Pupilstop = None, nmodes: int = None, wavelengthInNm: float = 0.0, dorms: bool = False, n_inputs: int = 1, remove_piston: bool = True, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Modal analysis processing object. Decomposition of an input ElectricField into modes defined by an influence function (e.g. Zernike polynomials).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.
unwrap_ls(phase_wrap)

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger
unwrap_2d

Parameters:

• ifunc (IFunc, optional) – Influence function object defining the modes (default: None)

• ifunc_inv (IFuncInv, optional) – Inverse influence function object (default: None). If both ifunc and ifunc_inv are provided, ifunc_inv will be used.

• type_str (str, optional) – Type of influence function to compute if ifunc is not provided (e.g. ‘zernike’) (default: None)

• npixels (int, optional) – Number of pixels across the pupil (required if ifunc is not provided)

• obsratio (float, optional) – Obscuration ratio for influence function computation (required if ifunc is not provided)

• diaratio (float, optional) – Diameter ratio for influence function computation (required if ifunc is not provided)

• pupilstop (Pupilstop, optional) – Pupil stop object defining the mask to apply to the influence functions (default: None)

• nmodes (int, optional) – Number of modes to compute (default: None, meaning all modes)

• wavelengthInNm (float, optional) – Wavelength in nanometers for phase to mode conversion (default: 0.0, meaning no conversion)

• dorms (bool, optional) – Whether to compute and output the RMS of the wavefront (default: False)

• n_inputs (int, optional) – Number of input electric fields to process (default: 1). If greater than 1, the in_ef_list input will be used instead of in_ef.

• remove_piston (bool, optional) – Whether to remove the global piston term from the modes when inverting the influence function (default: True)

• target_device_idx (int [1], optional) – Target device for computation (-1 for CPU, >=0 for GPU)

• precision (int [1], optional) – Numerical precision (0 for double, 1 for single)

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.
unwrap_ls(phase_wrap)

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger
unwrap_2d

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

unwrap_2d(p)

unwrap_ls(phase_wrap)

Modalrec

class specula.processing_objects.modalrec.Modalrec(recmat: Recmat, nmodes: int = None, ncutmodes: int = None, target_device_idx: int = None, precision: int = None)

Bases: BaseModalrec

Standard modal reconstructor processing object. Performs pure matrix-vector multiplication: modes = recmat @ slopes.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Modalrec Explicit Polc

class specula.processing_objects.modalrec_explicit_polc.ModalrecExplicitPolc(recmat: Recmat, projmat: Recmat = None, intmat: Intmat = None, nSlopesToBeDiscarded: int = None, target_device_idx: int = None, precision: int = None)

Bases: BaseModalrec

Explicit Pseudo Open Loop Control (POLC) modal reconstructor processing object.

This class explicitly reconstructs the slopes by summing the measured slopes and the estimated commands contribution (via interaction matrix), and then subtracts the applied commands from the projected modes.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Modalrec Implicit Polc

class specula.processing_objects.modalrec_implicit_polc.ModalrecImplicitPolc(recmat: Recmat, projmat: Recmat, intmat: Intmat, target_device_idx: int = None, precision: int = None)

Bases: BaseModalrec

POLC modal reconstructor processing object. Uses implicit Pseudo Open Loop Control (POLC) to reduce computational cost.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Modalrec Multirate

class specula.processing_objects.modalrec_multirate.ModalrecMultirate(recmat_list: List[Recmat], validity_masks: List[List[bool]], n_modes_total: int, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Multirate Tomographic Reconstructor processing object (for MORFEO-like systems).

This object dynamically selects the appropriate Reconstruction Matrix (Recmat) based on which sensors have provided a new measurement at the current time step.

It mathematically slices the selected matrix into N blocks (one per sensor), outputting N independent modal vectors of size M. The downstream multirate controller will fuse these partial modal projections.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• recmat_list (list of Recmat) – Ordered list of reconstruction matrices, one for each validity state. Matrices are expected to use the full sensor-vector geometry.

• validity_masks (list of list of bool) – Boolean masks associated with each matrix in recmat_list, using the same ordering.

• n_modes_total (int [1]) – Total size of each output modal vector.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Modulated Double Roof

class specula.processing_objects.modulated_double_roof.ModulatedDoubleRoof(simul_params: SimulParams, wavelengthInNm: float, fov: float, pup_diam: int, output_resolution: int, mod_amp: float = 3.0, mod_step: int = None, fov_errinf: float = 0.5, fov_errsup: float = 2, pup_dist: int = None, pup_margin: int = 2, fft_res: float = 3.0, fp_obs: float = None, pup_shifts=(0.0, 0.0), pyr_tlt_coeff: float = None, pyr_edge_def_ld: float = 0.0, pyr_tip_def_ld: float = 0.0, pyr_tip_maya_ld: float = 0.0, min_pup_dist: float = None, rotAnglePhInDeg: float = 0.0, xShiftPhInPixel: float = 0.0, yShiftPhInPixel: float = 0.0, target_device_idx: int = None, precision: int = None)

Bases: ModulatedPyramid

Pyramid wavefront sensor with double roof processing object. Includes tip-tilt modulation and double roof.

Methods

cache_ttexp()	Cache tip/tilt exponentials for modulation or extended source
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_tlt_f(p, c)	Generate tilt factor for pyramid de-rotation
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
calc_pyr_geometry
capture_stream
check_ready
device_stream
get_fp_mask
get_modulation_tilts
get_pyr_tlt
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

cache_ttexp()	Cache tip/tilt exponentials for modulation or extended source
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_tlt_f(p, c)	Generate tilt factor for pyramid de-rotation
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
calc_pyr_geometry
capture_stream
check_ready
device_stream
get_fp_mask
get_modulation_tilts
get_pyr_tlt
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

get_pyr_tlt(p, c)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.modulated_double_roof.pyr1_abs2(v, norm, ffv, xp)

specula.processing_objects.modulated_double_roof.pyr1_fused(u_fp, ffv, fpsf, masked_exp, xp)

Modulated Pyramid

class specula.processing_objects.modulated_pyramid.ModulatedPyramid(simul_params: SimulParams, wavelengthInNm: float, fov: float, pup_diam: int, output_resolution: int, mod_amp: float = 3.0, mod_step: int = None, mod_type: str = 'circular', fov_errinf: float = 0.1, fov_errsup: float = 2, pup_dist: int = None, pup_margin: int = 2, fft_res: float = 3.0, fp_obs: float = None, pup_shifts=(0.0, 0.0), pyr_tlt_coeff: float = None, pyr_edge_def_ld: float = 0.0, pyr_tip_def_ld: float = 0.0, pyr_tip_maya_ld: float = 0.0, min_pup_dist: float = None, rotAnglePhInDeg: float = 0.0, xShiftPhInPixel: float = 0.0, yShiftPhInPixel: float = 0.0, magnification: float = 1.0, force_extrapolation: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Pyramid wavefront sensor processing object. Includes tip-tilt modulation.

This class implements a modulated pyramid WFS that works with point sources or can be used as a base class for extended source implementations. The modulation can be circular (standard), or linear (vertical, horizontal, alternating).

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing pixel_pupil and pixel_pitch

• wavelengthInNm (float [nm]) – Working wavelength in nanometers

• fov (float [arcsec]) – Field of view in arcseconds (a field stop may be applied in the focal plane to limit FoV)

• pup_diam (int [pixels]) – Pupil diameter in pixels

• output_resolution (int [pixels]) – Output CCD side length in pixels

• mod_amp (float [lambda/D], optional) – Modulation amplitude in lambda/D units (default: 3.0)

• mod_step (int [1], optional) – Number of modulation steps. If None, automatically calculated based on mod_amp and mod_type (default: None)

• mod_type (str) – Modulation type: ‘circular’, ‘vertical’, ‘horizontal’, or ‘alternating’ (default: ‘circular’)

• fov_errinf (float [1], optional) – Accepted error in reducing FoV (default: 0.1, i.e., -10%)

• fov_errsup (float [1], optional) – Accepted error in enlarging FoV (default: 2.0, i.e., +100%)

• pup_dist (int [pixels], optional) – Pupil distance in pixels. If None, calculated from pup_diam and pup_margin

• pup_margin (int [pixels], optional) – Margin around pupils in pixels (default: 2)

• fft_res (float [1], optional) – Minimum PSF sampling (default: 3.0, i.e., 3 pixels per PSF FWHM i.e. lambda/D)

• fp_obs (float [pixels], optional) – Focal plane central obstruction diameter in pixels (default: None)

• pup_shifts (tuple [pixels], optional) – Static pupil shifts in pixels (x, y) (default: (0.0, 0.0))

• pyr_tlt_coeff (float [1], optional) – Pyramid tilt coefficients for custom face geometry (default: None) WARNING: not implemented/tested yet

• pyr_edge_def_ld (float [lambda/D], optional) – Edge defect size in lambda/D units (default: 0.0)

• pyr_tip_def_ld (float [lambda/D], optional) – Tip defect size in lambda/D units (default: 0.0)

• pyr_tip_maya_ld (float [lambda/D], optional) – Maya Pyramid (i.e. flat tip) defect size in lambda/D units (default: 0.0)

• min_pup_dist (float [pixels], optional) – Minimum pupil distance constraint (default: None)

• rotAnglePhInDeg (float [deg], optional) – Rotation angle of input phase in degrees (default: 0.0)

• xShiftPhInPixel (float [pixels], optional) – X shift of input phase in pixels (default: 0.0)

• yShiftPhInPixel (float [pixels], optional) – Y shift of input phase in pixels (default: 0.0)

• magnification (float [1], optional) – Magnification factor applied to input phase (default: 1.0)

• force_extrapolation (bool) – Force extrapolation of input electric field (required by SprintPyr)

• target_device_idx (int [1], optional) – GPU device index (default: None, uses default device, -1 for CPU)

• precision (int [1], optional) – Numerical precision: 32 (1) or 64 (0) bits (default: None, uses system default)

Notes

The modulation types have different characteristics: - ‘circular’: Standard pyramid modulation, uniform flux distribution - ‘vertical’/’horizontal’: Linear modulation along one axis, flux weighted by 1/cos(tilt) - ‘alternating’: Switches between vertical and horizontal on consecutive frames - pyr_tip_def_ld and pyr_tip_maya_ld represent different types of pyramid tip imperfections.

For linear modulation, the flux weighting compensates for intensity loss at large tilts, ensuring uniform contribution from all modulation positions.

Methods

cache_ttexp()	Cache tip/tilt exponentials for modulation or extended source
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_tlt_f(p, c)	Generate tilt factor for pyramid de-rotation
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
calc_pyr_geometry
capture_stream
check_ready
device_stream
get_fp_mask
get_modulation_tilts
get_pyr_tlt
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

cache_ttexp()	Cache tip/tilt exponentials for modulation or extended source
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_tlt_f(p, c)	Generate tilt factor for pyramid de-rotation
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
calc_pyr_geometry
capture_stream
check_ready
device_stream
get_fp_mask
get_modulation_tilts
get_pyr_tlt
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

cache_ttexp()

Cache tip/tilt exponentials for modulation or extended source

calc_pyr_geometry(DpupPix, pixel_pitch, lambda_, FoV, pup_diam, ccd_side, fov_errinf=0.1, fov_errsup=0.5, pup_dist=None, pup_margin=2, fft_res=3.0, min_pup_dist=None)

get_fp_mask(totsize, mask_ratio, obsratio=0)

get_modulation_tilts(p)

get_pyr_tlt(p, c)

get_tlt_f(p, c)

Generate tilt factor for pyramid de-rotation

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.modulated_pyramid.pyr1_abs2(v, norm, ffv, xp)

specula.processing_objects.modulated_pyramid.pyr1_fused(u_fp, ffv, fpsf, masked_exp, xp)

Multi Im Calibrator

class specula.processing_objects.multi_im_calibrator.MultiImCalibrator(nmodes: int, n_inputs: int, data_dir: str, im_tag: str = None, full_im_tag: str = None, overwrite: bool = False, pupilstop: Pupilstop = None, source_dict: list = None, dm: DM = None, sensor_dict: list = None, slopec_dict: list = None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Multiple IM calibrator processing object. Interaction matrix calibrator for multiple sources/sensors pairs

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Multi Rec Calibrator

class specula.processing_objects.multi_rec_calibrator.MultiRecCalibrator(nmodes: int, data_dir: str, rec_tag: str = None, full_rec_tag: str = None, overwrite: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Multiple reconstructor calibrator processing object. Calibrates reconstruction matrices for multiple sources/sensors pairs

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
full_rec_path
init_logging
input_names
monitorMem
output_names
printMemUsage
rec_path
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
full_rec_path
init_logging
input_names
monitorMem
output_names
printMemUsage
rec_path
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

full_rec_path()

classmethod input_names()

classmethod output_names()

rec_path(i)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Multirate Complementary Filter

class specula.processing_objects.multirate_complementary_filter.MultirateComplementaryFilter(iir_filter_data: IirFilterData, g_track: float, weights: list, N_list: list, delay: float = 0, idx_yf=None, idx_ys=None, validate_sync: bool = True, target_device_idx=None, precision=None)

Bases: BaseFilter

Multirate filter for differential sensor fusion (Generalized Barycentric Approach).

Inherits from BaseFilter to support delay, gain_mod, and POLC synchronous outputs.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset filter internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement filter-specific computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• iir_filter_data (IirFilterData) – IIR controller coefficients for the fused command.

• g_track (float [1]) – Tracking gain applied to the barycentric slow-sensor contribution.

• weights (list [1]) – DC fusion weights for [fast_sensor, slow_sensor_1, ...].

• N_list (list [1]) – Downsampling factors for the slow sensors, in the same order as in_ys.

• delay (float [1], optional) – Output delay in frames.

• idx_yf (optional [1]) – Index selections used when routing inputs from a single in_vec vector.

• idx_ys (optional [1]) – Index selections used when routing inputs from a single in_vec vector.

• validate_sync (bool) – If True, enforce explicit multirate timestamp consistency on separate inputs. Set it to False when slow branches are already zero-stuffed upstream.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset filter internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement filter-specific computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implement filter-specific computation.

Must populate self.output_buffer[:, 0] with current output.

Mvm

class specula.processing_objects.mvm.MVM(recmat: Recmat, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Matrix-Vector Multiplication processing object. Simplified modal reconstructor for BaseValue inputs

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Optical Gain Estimator

class specula.processing_objects.optical_gain_estimator.OpticalGainEstimator(gain: float, initial_optical_gain: float = 1.0, open_loop_estimate: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Optical Gain Estimator processing object. Estimates optical gain based on demodulated signals.

Uses two demodulated values (from delta-command and command) to estimate the optical gain of the system.

By default, the optical gain is updated using: opticalGain = opticalGain - (1 - demod_delta_cmd/demod_cmd) * gain * opticalGain

When the optical gain is NOT compensated in closed loop (open_loop_estimate = True), the estimator is a simple integrator: opticalGain = opticalGain * (1-gain) + (demod_delta_cmd/demod_cmd) * gain

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Papl Coronagraph

class specula.processing_objects.papl_coronagraph.PAPLCoronagraph(simul_params: SimulParams, wavelengthInNm: float, pupil, contrastInDarkHole: float, iwaInLambdaOverD: float, owaInLambdaOverD: float, fpmIWAInLambdaOverD: float, fpmOWAInLambdaOverD: float = None, knife_edge: bool = True, outerStopAsRatioOfPupil: float = 1.0, innerStopAsRatioOfPupil: float = 0.0, fft_res: float = 3.0, make_symmetric: bool = False, beta: float = 0.9, target_device_idx: int = None, precision: int = None)

Bases: APPCoronagraph

Phase-apodized-pupil Lyot (PAPL) coronagraph class. This class implements a PAPL coronagraph, which uses a phase-only mask in the pupil plane to create a dark hole in the focal plane.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
define_apodizing_phase
device_stream
init_logging
input_names
make_pupil_stop
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters containing pixel_pupil and pixel_pitch

• wavelengthInNm (float) – Wavelength in nm

• fov (float) – Desired field of view in lambda/D on focal plane

• fov_errinf (float, optional) – Relative error allowed on the inner part of the FOV (default: 0.1)

• fov_errsup (float, optional) – Relative error allowed on the outer part of the FOV (default: 10)

• fft_res (float, optional) – Desired resolution in the focal plane in pixels per lambda/D (default: 3.0)

• center_on_pixel (bool, optional) – Whether to center the focal plane mask on a single pixel (True) or at the intersection of 4 pixels (False). This affects the phase shift applied to the electric field (default: True)

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Override this method to create the desired focal plane (complex) mask
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
define_apodizing_phase
device_stream
init_logging
input_names
make_pupil_stop
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

make_focal_plane_mask()

Override this method to create the desired focal plane (complex) mask

make_pupil_stop()

Phase Extractor

class specula.processing_objects.phase_extractor.PhaseExtractor(target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Phase extractor processing object. Extracts the phase (phaseInNm) from an ElectricField or Layer and stores it as a BaseValue, preserving the original 2-D shape.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Phase extractor processing object.

Reads an ElectricField (or Layer, which is a subclass) and copies its phaseInNm 2-D array into a BaseValue output, preserving the original shape.

Parameters:

• target_device_idx (int [1], optional) – Target device index (CPU/GPU). If None, a global setting is used.

• precision (int [1], optional) – Precision (0 = double, 1 = single). If None, a global setting is used.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Phase Flattening

class specula.processing_objects.phase_flattening.PhaseFlattening(target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Phase flattening processing object. Removes the mean phase from an input electric field.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Phase Screen Cube

class specula.processing_objects.phase_screen_cube.PhaseScreenCube(simul_params: SimulParams, cube: SpatioTempArray, pixel_scale: float, source_dict: dict = None, layer_height: float = 0.0, scale_factor: float = 1.0, target_device_idx=None)

Bases: BaseProcessingObj

User-defined phase screen cube data object. Applies a spatio-temporal phase screen cube on the specified line of sight. The cube’s temporal sampling does not need to match the simulation’s sampling.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
initScreens()	Initialize phase screens from the cube data object.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters object containing pupil size, pixel pitch, zenith angle, etc.

• cube (SpatioTempArray) – Spatio-temporal array containing the phase screen cube. Internally data are accessed as time-first: shape (time, x, y). The phase screens should be in nm. The time_vector must be provided in seconds.

• pixel_scale (float [m]) – Phase screens’ pixel size in m.

• source_dict (dict [1], optional) – Dictionary of the source corresponding to the line of sight of the phase screen. If omitted or empty, the object exposes a single pair of outputs named out_ef and out_layer.

• layer_height (float [m], optional) – Height in meters assigned to the output layer, by default 0.0.

• scale_factor (float [1], optional) – Scaling factor applied to the phase screens, by default 1.0. This can be used to adjust the amplitude of the phase screens if needed.

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
initScreens()	Initialize phase screens from the cube data object.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

initScreens()

Initialize phase screens from the cube data object. Computes the scaling factor to map the cube spatial dimensions to the pupil grid.

classmethod output_names()

prepare_trigger(t)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Poly Chrom Sh

class specula.processing_objects.poly_chrom_sh.PolyChromSH(wavelengthInNm: list, flux_factor: list, subap_wanted_fov: float, sensor_pxscale: float, subap_on_diameter: int, subap_npx: int, squaremask: bool = True, fov_ovs_coeff: float = 0, xShiftPhInPixel: float = 0, yShiftPhInPixel: float = 0, rotAnglePhInDeg: float = 0, set_fov_res_to_turbpxsc: bool = False, laser_launch_tel: LaserLaunchTelescope = None, subap_rows_slice=None, xy_tilts_in_arcsec: list = None, target_device_idx: int = None, precision: int = None)

Bases: PolyChromWFS

Polychromatic Shack-Hartmann sensor that wraps multiple monochromatic SH sensors.

Each SH can have its own wavelength, QE factor, and differential tilt.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_wavelength_contribution(index)	Get the intensity contribution from a specific wavelength.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_wavelength_contribution(index)	Get the intensity contribution from a specific wavelength.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Poly Chrom Wfs

class specula.processing_objects.poly_chrom_wfs.PolyChromWFS(wavelengthInNm: list, ccd_side: int, flux_factor: list, xy_tilts_in_arcsec: list = None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Poly-chromatic WFS abstract processing object. Base class for polychromatic wavefront sensors which handles multiple wavelengths, flux factors, tilts, and output normalization.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_wavelength_contribution(index)	Get the intensity contribution from a specific wavelength.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_wavelength_contribution(index)	Get the intensity contribution from a specific wavelength.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

check_ready(t)

get_wavelength_contribution(index)

Get the intensity contribution from a specific wavelength.

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Poly Crom Pyramid

class specula.processing_objects.poly_crom_pyramid.PolyCromPyramid(wavelengthInNm: list, flux_factor: list, simul_params: SimulParams, fov: float, pup_diam: int, output_resolution: int, mod_amp: float = 3.0, mod_step: int = None, mod_type: str = 'circular', fov_errinf: float = 0.5, fov_errsup: float = 2, pup_dist: int = None, pup_margin: int = 2, fft_res: float = 3.0, fp_obs: float = None, pup_shifts=(0.0, 0.0), pyr_tlt_coeff: float = None, pyr_edge_def_ld: float = 0.0, pyr_tip_def_ld: float = 0.0, pyr_tip_maya_ld: float = 0.0, min_pup_dist: float = None, rotAnglePhInDeg: float = 0.0, xShiftPhInPixel: float = 0.0, yShiftPhInPixel: float = 0.0, xy_tilts_in_arcsec: list = None, target_device_idx: int = None, precision: int = None)

Bases: PolyChromWFS

Poly-chromatic Pyramid sensor processing object. Wraps multiple monochromatic ModulatedPyramid sensors, each of which can have its own wavelength, flux factor, and differential tilt.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_wavelength_contribution(index)	Get the intensity contribution from a specific wavelength.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_wavelength_contribution(index)	Get the intensity contribution from a specific wavelength.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Power Loss

class specula.processing_objects.power_loss.PowerLoss(simul_params: SimulParams, wavelengthInNm: float, nd: int, prop_distance: float, receiver_diam: float, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Power Loss processing object. Computes power loss in dB from the flux at the sensor and the receiver diameter.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Psf

class specula.processing_objects.psf.PSF(simul_params: SimulParams, wavelengthInNm: float, nd: float = None, pixel_size_mas: float = None, start_time: float = 0.0, compute_profile_metrics: bool = False, compute_metrics_in_trigger: bool = False, ee_radius_in_lambda_d=None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Point Spread Function (PSF) processing object. Computes PSF, Strehl ratio (SR), integrated PSF and SR, and PSF standard deviation over time from an input ElectricField.

Parameters:

• simul_params (SimulParams) – Simulation parameters object.

• wavelengthInNm (float [nm]) – Wavelength at which to compute the PSF [nm].

• nd (float [1], optional) – Numerical density of the PSF (pixels per lambda/D). If None, it is calculated based on the input ElectricField and pixel size.

• pixel_size_mas (float [mas], optional) – Desired pixel size of the PSF in milliarcseconds. If None, it is calculated based on the input ElectricField and numerical density.

• start_time (float [s], optional) – Time (in seconds) after which to start integrating PSF and SR. Default is 0.0.

• compute_profile_metrics (bool) – If True, also compute radial profile, FWHM and encircled-energy outputs. By default these summary metrics are evaluated in finalize() only.

• compute_metrics_in_trigger (bool) – If True and compute_profile_metrics is enabled, also update the same metrics after each trigger.

• ee_radius_in_lambda_d (float or array-like [lambda/D], optional) – Radius or radii in units of lambda/D at which to return the encircled energy.

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Psf Coronagraph

class specula.processing_objects.psf_coronagraph.PsfCoronagraph(simul_params: SimulParams, wavelengthInNm: float, nd: float = None, use_average_field: bool = True, pixel_size_mas: float = None, start_time: float = 0.0, compute_profile_metrics: bool = False, compute_metrics_in_trigger: bool = False, ee_radius_in_lambda_d=None, target_device_idx: int = None, precision: int = None)

Bases: PSF

Perfect coronagraph processing object.. The implementation includes the standard PSF calculation as it inherits from the PSF class.

Parameters:

• simul_params (SimulParams) – Simulation parameters object.

• wavelengthInNm (float [nm]) – Wavelength at which to compute the PSF [nm].

• nd (float [1], optional) – Numerical density of the PSF (pixels per lambda/D). If None, it is calculated based on the input ElectricField and pixel size.

• use_average_field (bool) – If True, the average electric field over the pupil is subtracted to compute the coronagraph PSF. If False, the perfect coronagraph formula is applied for the computation. Default is True (average field removal). The perfect coronagraph formula is Equation (1) in Cavarroc et al. 2006

• pixel_size_mas (float [mas], optional) – Desired pixel size of the PSF in milliarcseconds. If None, it is calculated based on the input ElectricField and numerical density.

• start_time (float [s], optional) – Time (in seconds) after which to start integrating PSF and SR. Default is 0.0.

• compute_profile_metrics (bool) – If True, compute coronagraph radial-profile outputs for the instantaneous, integrated and standard-deviation coronagraph PSFs.

• compute_metrics_in_trigger (bool) – If True, update those metrics after each trigger as well.

• ee_radius_in_lambda_d (float or array-like [lambda/D], optional) – Radius or radii in units of lambda/D at which to return the encircled energy.

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

calc_coronagraph_psf(phase, amp[, imwidth, ...])	Calculate coronagraph PSF using perfect coronagraph theory.
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

calc_coronagraph_psf(phase, amp[, imwidth, ...])	Calculate coronagraph PSF using perfect coronagraph theory.
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

calc_coronagraph_psf(phase, amp, imwidth=None, normalize=False, nocenter=False)

Calculate coronagraph PSF using perfect coronagraph theory. The perfect coronagraph subtracts the average electric field over the pupil.

Parameters: phase : ndarray

2D phase array

ampndarray

2D amplitude array

imwidthint, optional

Width of output image

normalizebool, optional

If True, normalize PSF

nocenterbool, optional

If True, don’t center the PSF

Returns: coronagraph_psf : ndarray

2D coronagraph PSF

finalize()

Override this method to perform any actions after the simulation is completed

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.psf_coronagraph.psf_abs2(v, xp)

Pupilstop Controller

class specula.processing_objects.pupilstop_controller.PupilstopController(pupilstop: Pupilstop, threshold_mask: bool = True, mask_threshold: float = 0.5, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Processing object that updates a Pupilstop object over time.

The object always triggers at each iteration so that the output pupilstop generation_time is refreshed regularly, even with static inputs.

Optional BaseValue inputs can drive geometry updates:

• in_rotation_deg: scalar rotation angle [deg]

• in_shift_xy_px: 2-element shift [x, y] in pixels

• in_magnification: scalar magnification factor (>0)

If any of the optional inputs are connected, the amplitude mask is regenerated every trigger from the initial mask applying the current geometry.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• pupilstop (Pupilstop) – The Pupilstop object to be controlled and updated.

• threshold_mask (bool, optional) – If True, the updated mask will be thresholded to binary values based on mask_threshold (default: True).

• mask_threshold (float [1], optional) – Threshold value for binarizing the mask if threshold_mask is True (default: 0.5).

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Push Pull Generator

class specula.processing_objects.push_pull_generator.PushPullGenerator(nmodes: int, first_mode: int = 0, push_pull_type: str = 'PUSHPULL', amp: float = None, constant_amp: bool = False, pattern: list = [1, -1], vect_amplitude: list = None, ncycles: int = 1, nsamples: int = 1, repeat_ncycles: bool = False, repeat_full_sequence: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseGenerator

Push-Pull Generator processing object. Generates push-pull signals for modal calibration.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

trigger_code()

Implement signal generation logic in subclasses

Pyr Pupdata Calibrator

class specula.processing_objects.pyr_pupdata_calibrator.PyrPupdataCalibrator(data_dir: str, dt: float = None, thr1: float = 0.1, thr2: float = 0.25, obs_thr: float = 0.8, slopes_from_intensity: bool = False, output_tag: str = None, auto_detect_obstruction: bool = True, min_obstruction_ratio: float = 0.05, display_debug: bool = False, overwrite: bool = False, save_on_exit: bool = True, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Pyramid PupData Calibrator processing object. Calibrator for pyramid pupils.

This processing object analyzes a calibration image containing four pyramid pupils to estimate their geometric properties (centers and radii), detect possible central obstructions, and generate pixel index maps for each pupil. The resulting data is stored in a PupData object.

Optional features include automatic central obstruction detection and debug plotting.

The calibration can operate on either intensity or pixel inputs and supports optional temporal integration, obstruction detection, and debug visualization.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main calibration function

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• data_dir (str) – Directory where calibration outputs are saved.

• dt (float [s], optional) – Integration time in seconds. If provided, frames are accumulated and processed only at multiples of dt.

• thr1 (float [1], optional) – First threshold for pupil segmentation. Default is 0.1.

• thr2 (float [1], optional) – Second threshold for refined segmentation. Default is 0.25.

• obs_thr (float [1], optional) – Scaling factor for obstruction detection. Default is 0.8.

• slopes_from_intensity (bool) – If True, generate pupil indices directly from intensity masks. Otherwise, use geometric translation. Default is False.

• output_tag (str) – Filename used when saving calibration results.

• auto_detect_obstruction (bool) – Enable automatic detection of central obstruction. Default is True.

• min_obstruction_ratio (float [1], optional) – Minimum allowed obstruction ratio. Default is 0.05.

• display_debug (bool) – If True, display debug plots during calibration. Default is False.

• overwrite (bool) – If True, overwrite existing files when saving. Default is False.

• save_on_exit (bool) – If True, automatically save calibration data on finalize. Default is True.

• target_device_idx (int [1], optional) – Target device index for computation.

• precision (int [1], optional) – Numerical precision for internal data.

Raises:

ValueError – If dt is provided and is not positive.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main calibration function

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Main calibration function

Pyr Slopec

class specula.processing_objects.pyr_slopec.PyrSlopec(pupdata: PupData, sn: Slopes = None, shlike: bool = False, norm_factor: float = None, thr_value: float = 0, slopes_from_intensity: bool = False, target_device_idx: int = None, precision: int = None, **kwargs)

Bases: Slopec

Pyramid slopes computer processing object. Computes pyramid slopes from pixel data using the 4 pupil intensities.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

nslopes()

nsubaps()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.pyr_slopec.clamp_generic_less(x, c, y, xp)

specula.processing_objects.pyr_slopec.clamp_generic_more(x, c, y, xp)

Random Generator

class specula.processing_objects.random_generator.RandomGenerator(distribution='NORMAL', amp: List[float] = None, constant: List[float] = None, seed: int = None, output_size: int = 0, modal_rms: float = None, forced_zero_modes: int = 0, scaling_law: str = 'INVERSE', target_device_idx: int = None, precision: int = None)

Bases: BaseGenerator

Random Generator processing object. Generates random signals (normal or uniform distribution).

Parameters: - distribution (str): ‘NORMAL’ or ‘UNIFORM’ (default: ‘NORMAL’) - amp (float) [1]: Amplitude of the random signal. For ‘NORMAL’, this is the standard deviation;

for ‘UNIFORM’, this is the width of the distribution. (default: None)

• constant (float) [1]: A constant offset added to the random signal (default: 0.0)

• seed (int) [1]: Seed for the random number generator (default: None, which means random seed)

• output_size (int) [1]: Number of random values to generate (default: 1)

• modal_rms (float) [1]: Desired RMS value for the modes (mutually exclusive with ‘amp’) (default: None)

• forced_zero_modes (int) [1]: Number of initial modes to force to 0.0

  (default: 0, must be <= output_size)

• scaling_law (str): The relationship between amplitude and radial order ‘n’ (options: ‘CONSTANT’,

  ‘INVERSE’, ‘LINEAR’) (default: ‘INVERSE’)

• target_device_idx (int) [1]: Index of the target device for computation (e.g., GPU) (default: None)

• precision (int) [1]: Numerical precision for the output (e.g., 32 or 64) (default: None)

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

trigger_code()

Implement signal generation logic in subclasses

Rec Calibrator

class specula.processing_objects.rec_calibrator.RecCalibrator(nmodes: int, data_dir: str, rec_tag: str, first_mode: int = 0, pupdata_tag: str = None, overwrite: bool = False, mmse: bool = False, r0: float = 0.15, L0: float = 25.0, dm: DM = None, noise_cov: float | ndarray | list = None, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Reconstruction matrix calibrator processing object. Analyzes an interaction matrix (Intmat) to compute a reconstruction matrix (Rec).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

classmethod input_names()

classmethod output_names()

Schedule Generator

class specula.processing_objects.schedule_generator.ScheduleGenerator(scheduled_values: list, scheduled_times: list, modes_per_group: list, target_device_idx: int = None, precision: int = None)

Bases: BaseGenerator

Schedule Generator processing object. Generates scheduled values which change at specified times.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

trigger_code()

Implement signal generation logic in subclasses

Sh

class specula.processing_objects.sh.SH(wavelengthInNm: float, subap_wanted_fov: float, sensor_pxscale: float, subap_on_diameter: int, subap_npx: int, squaremask: bool = True, fov_ovs_coeff: float = 2.0, xShiftPhInPixel: float = 0, yShiftPhInPixel: float = 0, rotAnglePhInDeg: float = 0, set_fov_res_to_turbpxsc: bool = False, laser_launch_tel: LaserLaunchTelescope = None, subap_rows_slice=None, data_dir: str = '', target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Shack-Hartmann wavefront sensor processing object. Takes an electric field as input and produces an intensity as output.

Parameters:

• wavelengthInNm (float [nm]) – Wavelength in nanometers

• subap_wanted_fov (float [arcsec]) – Desired subaperture Field of View in arcseconds

• sensor_pxscale (float [arcsec/pixel]) – Sensor pixel scale in arcseconds/pixel

• subap_on_diameter (int [1]) – Subaperture diameter in meters

• subap_npx (int [pixels]) – Number of pixels across the subaperture on the sensor

• squaremask (bool) – If True, use a square mask in the focal plane. Default is True.

• fov_ovs_coeff (float [1], optional) – Coefficient to determine the oversampling of the FoV. A value larger than 1 is recommended to avoid FFT wrapping effects. Default is 2.0.

• xShiftPhInPixel (float [pixels], optional) – Shift of the phase in the x direction in pixels. Default is 0.

• yShiftPhInPixel (float [pixels], optional) – Shift of the phase in the y direction in pixels. Default is 0.

• rotAnglePhInDeg (float [deg], optional) – Rotation angle of the phase in degrees. Default is 0.

• set_fov_res_to_turbpxsc (bool) – If True, set the FoV resolution to the turbulence pixel scale. Default is False.

• laser_launch_tel (LaserLaunchTelescope) – If provided, use the laser launch telescope parameters for kernel generation. Default is None.

• subap_rows_slice (slice [1], optional) – Slice object to specify which rows of subapertures to process. Default is None (process all rows).

• data_dir (str) – Directory for data files needed by the kernel object. Default is “”. Set by simul object if not provided.

• target_device_idx (int [1], optional) – Target device index for GPU processing. Default is None (CPU).

• precision (int [1], optional) – Numerical precision (e.g., 32 or 64). Default is None (use default precision).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.sh.abs2(u_fp, out, xp)

Sh Slopec

class specula.processing_objects.sh_slopec.ShSlopec(subapdata: SubapData, sn: Slopes = None, thr_value: float = -1, exp_weight: float = 1.0, filtmat=None, weightedPixRad: float = 0.0, windowing: bool = False, weight_int_pixel_dt: float = 0, window_int_pixel: bool = False, window_int_threshold: float = 1.0, vecWeiPixRadT: list = None, interleave: bool = False, target_device_idx: int = None, precision: int = None)

Bases: Slopec

Shack-Hartmann slopes computer processing object. Computes Shack-Hartmann slopes from pixel data using the subaperture intensities.

Attributes:

subap_idx

Methods

calc_slopes_nofor()	Calculate slopes without a for-loop over subapertures.
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
computeXYweights(np_sub, exp_weight, ...[, ...])	Compute XY weights for SH slope computation.
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
psf_gaussian(np_sub, fwhm)	Generates a 2D Gaussian PSF.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
printMemUsage
seconds_to_t
send_remote_output
set_xy_weights
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Attributes:

subap_idx

Methods

calc_slopes_nofor()	Calculate slopes without a for-loop over subapertures.
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
computeXYweights(np_sub, exp_weight, ...[, ...])	Compute XY weights for SH slope computation.
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
psf_gaussian(np_sub, fwhm)	Generates a 2D Gaussian PSF.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
printMemUsage
seconds_to_t
send_remote_output
set_xy_weights
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

calc_slopes_nofor()

Calculate slopes without a for-loop over subapertures.

computeXYweights(np_sub, exp_weight, weightedPixRad, quadcell_mode=False, windowing=False)

Compute XY weights for SH slope computation.

Parameters: np_sub (int): Number of subapertures. exp_weight (float): Exponential weight factor. weightedPixRad (float): Radius for weighted pixels. quadcell_mode (bool): Whether to use quadcell mode. windowing (bool): Whether to apply windowing.

nslopes()

nsubaps()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

psf_gaussian(np_sub, fwhm)

Generates a 2D Gaussian PSF.

Parameters:

• np_sub (int) – Number of sub-apertures (pixels) in one dimension.

• fwhm (list) – Full width at half maximum (FWHM) in pixels for x and y directions.

Returns:

2D array representing the Gaussian PSF.

Return type:

np.ndarray

set_xy_weights()

property subap_idx

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.sh_slopec.clamp_generic_less(x, c, y, xp)

specula.processing_objects.sh_slopec.clamp_generic_more(x, c, y, xp)

Sh Subap Calibrator

class specula.processing_objects.sh_subap_calibrator.ShSubapCalibrator(subap_on_diameter: int, data_dir: str, energy_th: float, output_tag: str, overwrite: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Shack-Hartmann Subaperture Calibrator processing object. Analyzes a calibration image to detect subaperture positions and generate a SubapData object.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

classmethod input_names()

classmethod output_names()

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Slopec

class specula.processing_objects.slopec.Slopec(sn: Slopes = None, recmat: Recmat = None, filt_intmat: Intmat = None, filt_recmat: Recmat = None, filtmat=None, weight_int_pixel_dt: float = 0, interleave: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Slope Computer abstract processing object. Base class for processing objects that compute slopes from pixel data, such as Shack-Hartmann or Pyramid slopes.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
nslopes()
nsubaps()
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
nslopes()
nsubaps()
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

do_accumulation(t)

Perform pixel accumulation based on the IDL version. This method should be called in trigger_code of derived classes.

classmethod input_names()

nslopes()

nsubaps()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Sn Calibrator

class specula.processing_objects.sn_calibrator.SnCalibrator(data_dir: str, output_tag: str, overwrite: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Slope null calibrator processing object. Analyzes a set of slope measurements to compute an average slope null, which is then saved as a Slopes object.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

finalize()

Override this method to perform any actions after the simulation is completed

classmethod input_names()

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Soft Limiter

class specula.processing_objects.soft_limiter.SoftLimiter(recmat_list: List[Recmat], gain: float = 1.0, start_time: float = 0.0, interval_time: float = 0.0, target_device_idx=None, precision=None)

Bases: BaseProcessingObj

Soft Limiter processing object.

A generalized temporal regularizer for unobservable or poorly sensed modes, based on a Minimum Mean Square Error (MMSE) subspace estimation. It acts as a localized leaky integrator to selectively prevent the control-induced divergence of specific modal subspaces without affecting the rest of the control loop.

Primary application: Specifically configured to mitigate the ‘Island Effect’ in segmented SCAO systems. It continuously drains unobservable differential pistons (petal modes) from the accumulated command state using von Kármán prior statistics, leaving the continuous atmospheric correction intact.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

setup()

Override this method to perform any setup just before the simulation is started.

The base class implementation also checks that all non-optional inputs have been set.

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Specula Input

class specula.processing_objects.specula_input.SpeculaInput(output_list: list, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Specula input processing object. Handles interactive inputs

This class is meant to provide outputs that can be set interactively and/or asynchronously wrt. the normal simulation run.

Derived classes must implement a function or callable that receives inputs from the “outside” and puts them into a queue that will be emptied at each trigger call. This function is registered passing it to “set_input_task”

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
set_input_task(task)	"task" must be a Python callable that accepts one argument.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Get new values from the input queue and set corresponding outputs, repeat until the input queue is empty.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
monitorMem
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

output_list: list of strings

List of output names to be generated

target_device_idxint, optional

Target device index for computation (CPU/GPU). Default is None (uses global setting).

precisionint, optional

Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
set_input_task(task)	"task" must be a Python callable that accepts one argument.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Get new values from the input queue and set corresponding outputs, repeat until the input queue is empty.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
monitorMem
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

set_input_task(task)

“task” must be a Python callable that accepts one argument. The argument will be set to a mp.Queue() instance, on which the callable must call put() with a tuple of two values: output name and output value.

trigger_code()

Get new values from the input queue and set corresponding outputs, repeat until the input queue is empty.

We don’t use self.q.empty() to check the queue status, since it does not guarantee that the subsequent get() won’t block.

Spot Monitor

class specula.processing_objects.spot_monitor.SpotMonitor(subapdata: SubapData, initial_alpha: float = 2.0, initial_gamma: float = 3.0, bounds_alpha=(0.5, 10.0), bounds_gamma=(0.1, None), target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Spot Monitor processing object. Monitors wavefront sensor spot quality by fitting a 2D Moffat profile.

• Input: Pixels (full WFS image)

• Uses SubapData to extract valid sub-apertures

• Sums all sub-apertures into a single np_sub x np_sub image

• Fits the summed spot with a 2D Moffat + constant sky (using astropy)

• Outputs: fit parameters, model image, residuals, summed image

Parameters:

• subapdata (SubapData) – Subaperture geometry and indexing information

• initial_alpha (float [1], optional) – Initial guess for Moffat alpha parameter (default: 2.0)

• initial_gamma (float [1], optional) – Initial guess for Moffat gamma parameter (default: 3.0)

• bounds_alpha (tuple [1], optional) – Bounds for alpha parameter (default: (0.5, 10.0))

• bounds_gamma (tuple [1], optional) – Bounds for gamma parameter (default: (0.1, None))

• target_device_idx (int [1], optional) – Target device index

• precision (int [1], optional) – Numerical precision

outputs[]

Summed subaperture image (np_sub x np_sub)

Type:

Pixels

outputs[]

Fitted Moffat model image

Type:

Pixels

outputs[]

Residuals (data - model)

Type:

Pixels

outputs[]

Array with 9 parameters: [0] amplitude - Moffat amplitude [1] x0 - centroid x position [2] y0 - centroid y position [3] gamma - Moffat gamma parameter [4] alpha - Moffat alpha parameter [5] sky - constant background level [6] fwhm - Full Width Half Maximum [7] chi2 - mean squared residual [8] success - 1.0 if fit converged, 0.0 otherwise

Type:

BaseValue

Attributes:

amplitude

Get fitted Moffat amplitude.

centroid

Get fitted centroid position (x0, y0).

fit_quality

Get fit quality metrics (chi2, success).

fwhm

Get fitted FWHM.

sky_level

Get fitted sky background level.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Update generation times for all outputs.
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main processing: sum subapertures and fit Moffat profile.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Attributes:

amplitude

Get fitted Moffat amplitude.

centroid

Get fitted centroid position (x0, y0).

fit_quality

Get fit quality metrics (chi2, success).

fwhm

Get fitted FWHM.

sky_level

Get fitted sky background level.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Update generation times for all outputs.
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main processing: sum subapertures and fit Moffat profile.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

property amplitude

Get fitted Moffat amplitude.

property centroid

Get fitted centroid position (x0, y0).

property fit_quality

Get fit quality metrics (chi2, success).

property fwhm

Get fitted FWHM.

classmethod input_names()

classmethod output_names()

post_trigger()

Update generation times for all outputs.

property sky_level

Get fitted sky background level.

trigger_code()

Main processing: sum subapertures and fit Moffat profile.

Sprint Pyr

SPRINT Estimator for Pyramid WFS.

class specula.processing_objects.sprint_pyr.SprintPyr(simul_params, dm, slopec, source, wfs, modes_index, carrier_frequencies, pupil_mask: Pupilstop = None, push_amp=10, estimation_dt=10.0, max_iterations=10, convergence_threshold=0.001, initial_misreg=None, apply_absolute_slopes=False, integration_gain=0.5, forgetting_factor=1.0, target_device_idx=None, precision=None)

Bases: BaseSprintEstimator

SPRINT (Pyramid WFS case) processing object. Computes interaction matrices and sensitivity matrices for Pyramid wavefront sensors, and estimates mis-registration parameters by fitting the measured interaction matrix.

Mis-registration parameters: - [0]: shift_x (pixels) - [1]: shift_y (pixels) - [2]: rotation (degrees) - [3]: magnification (fractional, added to 1.0)

Anisotropic magnification is not currently implemented in the Pyramid case.

Parameters:

• push_amp (float [nm]) – Amplitude of the push-pull perturbation for sensitivity matrix estimation (default: 10 nm)

• BaseSprintEstimator. (All parameters inherited from)

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)	Collect slopes for demodulation
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Initialize with Pyramid-specific parameters and build internal pipeline
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main SPRINT estimation logic

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize Pyramid SPRINT estimator.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)	Collect slopes for demodulation
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Initialize with Pyramid-specific parameters and build internal pipeline
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main SPRINT estimation logic

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

setup()

Initialize with Pyramid-specific parameters and build internal pipeline

Sprint Sh Synim

SPRINT Estimator for Shack-Hartmann WFS using SynIM for IM computation.

class specula.processing_objects.sprint_sh_synim.SprintShSynim(simul_params, dm, slopec, source, wfs, modes_index, carrier_frequencies, enable_wpup_magn_xy=False, estimation_dt=10.0, max_iterations=10, convergence_threshold=0.001, initial_misreg=None, apply_absolute_slopes=False, integration_gain=0.5, forgetting_factor=1.0, target_device_idx=None, precision=None)

Bases: BaseSprintEstimator

SPRINT (Shack-Hartmann WFS case) processing object. Uses SynIM library to computes interaction matrices and sensitivity matrices for Shack-Hartmann wavefront sensors and estimates mis-registration parameters by fitting the measured interaction matrix.

Mis-registration parameters: - [0]: shift_x (pixels) - [1]: shift_y (pixels) - [2]: rotation (degrees) - [3]: magnification (fractional, added to 1.0)

If enable_wpup_magn_xy=True (not yet implemented in SynIM): - [4]: magn_x (fractional) - [5]: magn_y (fractional)

Parameters:

• enable_wpup_magn_xy (bool) – Enable separate X/Y magnification parameters (default: False)

• BaseSprintEstimator. (All other parameters inherited from)

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)	Collect slopes for demodulation
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Initialize with SH-specific parameters
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main SPRINT estimation logic

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize SH SPRINT estimator with SynIM backend.

Parameters:

enable_wpup_magn_xy (bool) – Enable separate X/Y magnification (future feature)

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)	Collect slopes for demodulation
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Initialize with SH-specific parameters
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Main SPRINT estimation logic

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

setup()

Initialize with SH-specific parameters

Ssr Filter

class specula.processing_objects.ssr_filter.SsrFilter(ssr_filter_data: SsrFilterData, delay: float = 0, output_uses_new_state: bool = True, target_device_idx=None, precision=None)

Bases: BaseFilter

State Space Representation filter processing object. Based on Time Control filter, which implements discrete-time state-space filtering.

Discrete-time state-space filtering implementation: x[k+1] = A*x[k] + B*u[k] y[k] = C*x[k’] + D*u[k]

where x[k’] is either x[k] or x[k+1] depending on output_uses_new_state parameter.

All filters are handled simultaneously with single matrix operations.

Parameters:

• ssr_filter_data (SsrFilterData) – State-space matrices (A, B, C, D) in block-diagonal form

• delay (float [1], optional) – Output delay in frames (default: 0)

• output_uses_new_state (bool) – If True, output equation uses updated state: y[k] = C*x[k+1] + D*u[k] If False, output equation uses current state: y[k] = C*x[k] + D*u[k] (default: True, which is standard for discrete integrators)

• target_device_idx (int [1], optional) – Target device index

• precision (int [1], optional) – Numerical precision

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset SSR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	State-space filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Note

Provides common functionality for:

• Delay buffer management

• Interpolation for fractional delays

• Gain modulation

• Synchronous (no-delay) outputs for POLC

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
reset_states()	Reset SSR internal states.
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	State-space filter computation.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

reset_states()

Reset SSR internal states.

trigger_code()

State-space filter computation.

Terminal Input

class specula.processing_objects.terminal_input.TerminalInput(*args, **kwargs)

Bases: SpeculaInput

Terminal input processing object. Handles input from a terminal.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
set_input_task(task)	"task" must be a Python callable that accepts one argument.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Get new values from the input queue and set corresponding outputs, repeat until the input queue is empty.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
monitorMem
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

output_list: list of strings

List of output names to be generated

target_device_idxint, optional

Target device index for computation (CPU/GPU). Default is None (uses global setting).

precisionint, optional

Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
set_input_task(task)	"task" must be a Python callable that accepts one argument.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Get new values from the input queue and set corresponding outputs, repeat until the input queue is empty.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
monitorMem
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

specula.processing_objects.terminal_input.print_help()

specula.processing_objects.terminal_input.terminal_task(q)

Time History Generator

class specula.processing_objects.time_history_generator.TimeHistoryGenerator(time_hist: TimeHistory, target_device_idx: int = None, precision: int = None)

Bases: BaseGenerator

Time History Generator processing object. Generates signals from pre-computed time history data.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

trigger_code()

Implement signal generation logic in subclasses

Vibration Generator

class specula.processing_objects.vibration_generator.VibrationGenerator(simul_params: SimulParams, nmodes: int, psd, freq, seed: int = 1987, start_from_zero: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseGenerator

Vibration Generator processing object. Generates vibration signals from PSD specifications.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

PSD-based vibration generation

For PASSATA compatibility, psd is a 2d array-like with modes on the first index, while freq is a 1d array-like or a 2d array-like with modes on the second index.

Parameters:

• simul_params (SimulParams object) – main simulation parameters. Only the total_time and time_step members are accessed

• nmodes (int [1]) – number of modes to generate

• psd (2d array-like [nm^2/Hz]) – psd for each mode, modes on first index: [mode, psd] Note: PSD units are [nm^2/Hz] since phase units are [nm]

• freq (1d or 2d array-like [Hz]) – frequency vector for each mode. If 1d, the same frequency vector will be replicated for all modes. If 2d, modes must be on the second index: [freq, mode]

• seed (int [1], optional) – generation seed for first mode, will be increment by 1 for each additonal mode

• start_from_zero (bool, optional) – if True, first data point for each mode is zero. Defaults to False

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

trigger_code()

Implement signal generation logic in subclasses

specula.processing_objects.vibration_generator.get_vibrations_time_hist(nmodes, psd, freq, seed=1987, samp_freq=1000, niter=1000, start_from_zero=False, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/specula/envs/latest/lib/python3.13/site-packages/numpy/__init__.py'>, dtype=<class 'numpy.float32'>, complex_dtype=<class 'numpy.complex64'>)

PSD-based vibration generation

For PASSATA compatibility, freq is a 2d array-like with modes on the second index.

Parameters:

• psd (2d array-like) – psd for each mode, modes on first index: [mode, psd] Note: PSD units are [nm^2/Hz] since phase units are [nm]

• freq (1d or 2d array-like) – frequency vector for each mode. If 1d, the same frequency vector will be replicated for all modes. If 2d, modes must be on the second index: [freq, mode]

• seed (int, optional) – generation seed for first mode, will be increment by 1 for each additonal mode

• samp_freq (float, optional) – PSD sampling frequency in Hz, default 1000

• niter (int, optional) – number of data points per mode to generate, default 1000

• start_from_zero (bool, optional) – if True, first data point for each mode is zero. Defaults to False

• xp (module, optional) – either np or cp

• dtype (dtype, optional) – dtype for results

• complex_dtype (dtype, optional) – dtype for complex numbers in PSD generation

Returns:

time_hist – time history as a [sample, mode] array

Return type:

2d array

Vortex Coronagraph

class specula.processing_objects.vortex_coronagraph.VortexCoronagraph(simul_params: SimulParams, wavelengthInNm: float, vortexCharge: float, innerStopAsRatioOfPupil: float = 0.0, outerStopAsRatioOfPupil: float = 1.0, addInVortex: bool = False, inVortexRadInLambdaOverD: float = None, inVortexCharge: int = None, inVortexShift: float = None, fft_res: float = 3.0, target_device_idx: int = None, precision: int = None)

Bases: Coronagraph

Vortex Coronagraph processing object. Implements a vortex coronagraph, where the focal plane mask applies an azimuthal phase delay that changes from 0 to 2 pi a number of times equal to the vortex charge; the pupil plane mask can include an inner and/or outer stop.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Make a 'vortex' mask, where the phase delay changes azimuthally from 0 to 2 pi a number of times equal to vortexCharge
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Parameters:

• simul_params (SimulParams) – Simulation parameters containing pixel_pupil and pixel_pitch

• wavelengthInNm (float) – Wavelength in nm

• fov (float) – Desired field of view in lambda/D on focal plane

• fov_errinf (float, optional) – Relative error allowed on the inner part of the FOV (default: 0.1)

• fov_errsup (float, optional) – Relative error allowed on the outer part of the FOV (default: 10)

• fft_res (float, optional) – Desired resolution in the focal plane in pixels per lambda/D (default: 3.0)

• center_on_pixel (bool, optional) – Whether to center the focal plane mask on a single pixel (True) or at the intersection of 4 pixels (False). This affects the phase shift applied to the electric field (default: True)

• target_device_idx (int [1], optional) – Target device index for computation (CPU/GPU). Default is None (uses global setting).

• precision (int [1], optional) – Precision for computation (0 for double, 1 for single). Default is None (uses global setting).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
make_apodizer()	Override this method to add an apodizer.
make_focal_plane_mask()	Make a 'vortex' mask, where the phase delay changes azimuthally from 0 to 2 pi a number of times equal to vortexCharge
make_pupil_plane_mask()	Override this method to create the desired pupil plane (complex) mask
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

make_focal_plane_mask()

Make a ‘vortex’ mask, where the phase delay changes azimuthally from 0 to 2 pi a number of times equal to vortexCharge

make_pupil_plane_mask()

Override this method to create the desired pupil plane (complex) mask

Wave Generator

class specula.processing_objects.wave_generator.WaveGenerator(wave_type='SIN', amp: List[float] = [0.0], freq: List[float] = [0.0], offset: List[float] = [0.0], constant: List[float] = [0.0], slope: List[float] = [0.0], output_size: int = None, target_device_idx: int = None, precision: int = None)

Bases: BaseGenerator

Wave Generator processing object. Generates periodic waveforms (SIN, SQUARE, TRIANGLE).

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implement signal generation logic in subclasses

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

trigger_code()

Implement signal generation logic in subclasses

Windowed Integration

class specula.processing_objects.windowed_integration.WindowedIntegration(simul_params: SimulParams, n_elem: int, dt: float, start_time: float = 0, update_time_on_dt: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseProcessingObj

Windowed Integration processing object. Implements a simple windowed integration of a signal.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
prepare_trigger(t)
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
output_names
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

classmethod input_names()

classmethod output_names()

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

Zernike Sensor

class specula.processing_objects.zernike_sensor.ZernikeSensor(simul_params, wavelengthInNm, fov, pup_diam, output_resolution, spot_radius_lambda: float = 1.0, phase_shift_pi: float = 0.5, fft_res: float = 4.0, target_device_idx=None, precision=None)

Bases: ModulatedPyramid

Zernike Sensor processing object. Based on phase-shifting focal-plane spot technique, the class inherits from ModulatedPyramid but replaces the pyramid structure with a π/2 (default value) phase-shifting spot in the focal plane.

Methods

cache_ttexp()	Cache tip/tilt exponentials for modulation or extended source
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_pyr_tlt(p, c)	Creates a phase-shifting focal-plane spot of self.phase_delay π.
get_tlt_f(p, c)	Generate tilt factor for pyramid de-rotation
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
calc_pyr_geometry
capture_stream
check_ready
device_stream
get_fp_mask
get_modulation_tilts
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

cache_ttexp()	Cache tip/tilt exponentials for modulation or extended source
checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
get_pyr_tlt(p, c)	Creates a phase-shifting focal-plane spot of self.phase_delay π.
get_tlt_f(p, c)	Generate tilt factor for pyramid de-rotation
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
calc_pyr_geometry
capture_stream
check_ready
device_stream
get_fp_mask
get_modulation_tilts
init_logging
input_names
monitorMem
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

get_pyr_tlt(p, c)

Creates a phase-shifting focal-plane spot of self.phase_delay π. This introduces a self.phase_delay π phase shift in a circular region centered on the focal plane, replacing the traditional pyramid structure.

Parameters:

• p – FFT sampling parameter

• c – FFT padding parameter

Returns:

2D array with phase shift in central spot

Return type:

phase_mask

Zwfs Slopec

class specula.processing_objects.zwfs_slopec.ZwfsSlopec(pup_diam: float, ccd_size: int, obsratio: float = None, sn: Slopes = None, target_device_idx: int = None, thr_value: float = 0.0, precision: int = None)

Bases: Slopec

Zernike WFS slopes computer processing object. Computes Zernike WFS slopes from pixel data using the pupil intensity.

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

Initialize the base processing object.

Parameters: precision (int, optional): if None will use the global_precision, otherwise pass 0 for double, 1 for single target_device_idx (int, optional): if None will use the default_target_device_idx, otherwise pass -1 for cpu, i for GPU of index i

Methods

checkInputTimes()	Determine whether this processing object needs to execute the trigger method, based on the input states
check_input_names()	Check that all input names declared in self.input_names are present in self.inputs
check_output_names()	Check that all output names declared in self.output_names are present in self.outputs
do_accumulation(t)	Perform pixel accumulation based on the IDL version.
finalize()	Override this method to perform any actions after the simulation is completed
get_all_inputs()	Perform get() on all inputs.
post_trigger()	Make sure we are using the correct device and that any previous CUDA graph has been synchronized
sanity_check()	Check that all inputs and outputs have been setup correctly.
send_outputs([skip_delayed, delayed_only, ...])	Send all remote outputs via MPI.
setup()	Override this method to perform any setup just before the simulation is started.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
trigger_code()	Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

addRemoteOutput
build_stream
capture_stream
check_ready
device_stream
init_logging
input_names
monitorMem
nslopes
nsubaps
output_names
prepare_trigger
printMemUsage
seconds_to_t
send_remote_output
startMemUsageCount
stopMemUsageCount
t_to_seconds
trigger

nslopes()

nsubaps()

classmethod output_names()

post_trigger()

Make sure we are using the correct device and that any previous CUDA graph has been synchronized

prepare_trigger(t)

trigger_code()

Implementations in derived classes should run GPU operations using the xp module on arrays allocated with self.xp.

Avoid explicit numpy or pure-Python operations and avoid using values from variables that are reallocated by prepare_trigger() or post_trigger().

When stream capture is enabled, a CUDA graph is generated, non-GPU operations are skipped, and GPU memory addresses from the first run are reused.

specula.processing_objects.zwfs_slopec.clamp_generic_less(x, c, y, xp)