Data Objects API

Data objects for representing simulation data.

Convolution Kernel

class specula.data_objects.convolution_kernel.ConvolutionKernel(dimx: int, dimy: int, pxscale: float, pupil_size_m: float, dimension: int, launcher_pos: list = [0.0, 0.0, 0.0], seeing: float = 0.0, launcher_size: float = 0.0, zfocus: float = 90000.0, theta: list = [0.0, 0.0], airmass: float = 1.0, oversampling: int = 1, return_fft: bool = True, positive_shift_tt: bool = True, data_dir: str = '', target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Convolution Kernel data object. This object stores the convolution kernels for Laser Guide Star (LGS) Shack-Hartmann wavefront sensing and performs the related computations.

Methods

calculate_lgs_map()	Calculate the LGS (Laser Guide Star) map based on current parameters.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
generate_hash(items)	Generate a hash for the current kernel settings.
get_value()	Get current kernels.
restore(filename[, target_device_idx, ...])	Restore a ConvolutionKernel object from a FITS file.
save(filename)	Save the kernel to a FITS file.
set_value(v)	Set new kernels.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

build
calculate_focus
from_header
get_fits_header
init_logging
monitorMem
prepare_for_sh
printMemUsage
process_kernels
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a ConvolutionKernel object.

Methods

calculate_lgs_map()	Calculate the LGS (Laser Guide Star) map based on current parameters.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
generate_hash(items)	Generate a hash for the current kernel settings.
get_value()	Get current kernels.
restore(filename[, target_device_idx, ...])	Restore a ConvolutionKernel object from a FITS file.
save(filename)	Save the kernel to a FITS file.
set_value(v)	Set new kernels.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

build
calculate_focus
from_header
get_fits_header
init_logging
monitorMem
prepare_for_sh
printMemUsage
process_kernels
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

build()

calculate_focus()

calculate_lgs_map()

Calculate the LGS (Laser Guide Star) map based on current parameters. This creates convolution kernels for each subaperture.

static from_header(hdr, target_device_idx=None)

generate_hash(items)

Generate a hash for the current kernel settings. This is used to check if the kernel needs to be recalculated.

Returns:

A hash string representing the current kernel settings.

Return type:

str

get_fits_header()

get_value()

Get current kernels. If real_kernels was deallocated, raise an error.

prepare_for_sh(sodium_altitude=None, sodium_intensity=None, current_time=None)

process_kernels(return_fft=False)

static restore(filename, target_device_idx=None, kernel_obj=None, return_fft=False)

Restore a ConvolutionKernel object from a FITS file.

Parameters:

• filename (str) – Path to the FITS file

• target_device_idx (int, optional) – Target device index for GPU processing

• return_fft (bool, optional) – Whether to return FFT of the kernel

Returns:

The restored ConvolutionKernel object

Return type:

ConvolutionKernel

save(filename)

Save the kernel to a FITS file.

Parameters:

• filename (str) – Path to save the FITS file

• hdr (fits.Header, optional) – Additional header information

Raises:

ValueError – If real_kernels has been deallocated

set_value(v)

Set new kernels. Arrays are not reallocated if real_kernels exists. If real_kernels was deallocated, it will be recreated.

specula.data_objects.convolution_kernel.lgs_map_sh(nsh, diam, rl, zb, dz, profz, fwhmb, ps, ssp, overs=2, theta=[0.0, 0.0], rprof_type=0, mask_pupil=False, pupil_weight=None, doCube=True, dtype=<class 'numpy.float32'>, xp=<module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/specula/envs/stable/lib/python3.13/site-packages/numpy/__init__.py'>)

It returns the pattern of Sodium Laser Guide Star images relayed by a Shack-Hartman lenlet array. Only geometrical propagation is taken in account (no diffraction effects). The beacon is simulated in the Sodium layer as a cilynder with gaussian radial profile and axially discretized in a given set of distances from the telescope entrance pupil with a given relative intensities. Currently only zenith telescope pointing is implemented :param nsh: Number of sub-apertures :type nsh: int :param diam: Telescope entrance pupil diameter [m] :type diam: float :param rl: Launcher position in meters [x, y, z] :type rl: list :param zb: distance from the telescope pupil of the sodium layer relayed on the SH focal plane [m] :type zb: float :param dz: N-elements vector of distances from zb of telescope on-axis sampling points of the sodium layer [m] :type dz: list :param profz: Sodium layer profile :type profz: list :param fwhmb: full with at high maximum of the section of the sodium beacon orthogonal to the telescope optical axis [on-sky arcsec] :type fwhmb: float :param ps: plate scale of the SH foval plane [arcsec/pix] :type ps: float :param ssp: Field of view sampling of the SH focal plane (ssp x ssp) [pix] :type ssp: int :param overs: Oversampling factor :type overs: int :param theta: Tip-tilt offsets in arcseconds [x, y] :type theta: list :param rprof_type: Radial profile type (0 for Gaussian, 1 for top-hat) :type rprof_type: int :param mask_pupil: Whether to apply a pupil mask :type mask_pupil: bool :param pupil_weight: Pupil mask weight :type pupil_weight: ndarray :param doCube: Whether to return a cube of kernels :type doCube: bool :param xp: The numpy or cupy module to use for calculations :type xp: module

Returns:

The calculated LGS map

Return type:

ccd (ndarray)

Electric Field

class specula.data_objects.electric_field.ElectricField(dimx: int, dimy: int, pixel_pitch: float, S0: float = 0.0, target_device_idx: int = None, precision: int = None, wavelengthInNm: float = None, wavelengthToleranceInNm: float = 0.1)

Bases: BaseDataObj

Electric field data object. This class represents a 2D electric field, storing both amplitude and phase information for each pixel in a rectangular grid.

Attributes:

A

phaseInNm

size

Methods

area()	Calculate the area of the electric field.
array_for_display()	Returns a 2D array suitable for display: the phase (in nm) masked by the amplitude.
compare(ef2)	Compare this ElectricField object with another ElectricField object.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
ef_at_lambda(wavelengthInNm[, slicey, ...])	Calculate the electric field at a given wavelength.
phi_at_lambda(wavelengthInNm[, slicey, slicex])	Calculate the phase of the electric field at a given wavelength.
product(ef2[, subrect])	Multiply the electric field by another electric field.
reset()	Reset to zero phase and unitary amplitude
resize(dimx, dimy[, pitch])	Resize the electric field
set_value(v)	Set new values for phase and amplitude
square_modulus(wavelengthInNm)	Compute the square modulus (intensity) of the electric field at a given wavelength.
sub_ef([xfrom, xto, yfrom, yto, idx])	Extract a subregion of the electric field.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

checkOther
from_header
get_fits_header
get_value
init_logging
masked_area
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

ElectricField data object.

This class represents a 2D electric field, storing both amplitude and phase information for each pixel in a rectangular grid. The field is stored as a 2x(dimx)x(dimy) array, where the first index (0) corresponds to amplitude and the second index (1) to phase (in nm).

Parameters:

• dimx (int [pixels]) – Number of pixels along the x-axis (width).

• dimy (int [pixels]) – Number of pixels along the y-axis (height).

• pixel_pitch (float [m]) – The dimension in meters of a pixel.

• S0 (float [ph/s/m^2/nm], optional) – Flux density in photons/s/m^2/nm (default: 0.0).

• target_device_idx (int [1], optional) – Device index for computation (default: None).

• precision (int [1], optional) – Precision for computation (default: None).

• wavelengthInNm (float [nm], optional) – Monochromatic wavelength tag in nanometers. If set, this electric field is considered valid only at that wavelength.

• wavelengthToleranceInNm (float [nm], optional) – Absolute tolerance in nanometers used when checking wavelength compatibility for wavelength-tagged fields (default: 0.1 nm).

pixel_pitch

The pixel pitch in meters.

Type:

float

S0

Optional parameter for the field.

Type:

float

field

The electric field array of shape (2, dimx, dimy), with amplitude and phase.

Type:

xp.ndarray

wavelengthInNm

Monochromatic wavelength tag in nanometers.

Type:

float or None

wavelengthToleranceInNm

Absolute tolerance in nanometers for wavelength compatibility checks.

Type:

float

Attributes:

A

phaseInNm

size

Methods

area()	Calculate the area of the electric field.
array_for_display()	Returns a 2D array suitable for display: the phase (in nm) masked by the amplitude.
compare(ef2)	Compare this ElectricField object with another ElectricField object.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
ef_at_lambda(wavelengthInNm[, slicey, ...])	Calculate the electric field at a given wavelength.
phi_at_lambda(wavelengthInNm[, slicey, slicex])	Calculate the phase of the electric field at a given wavelength.
product(ef2[, subrect])	Multiply the electric field by another electric field.
reset()	Reset to zero phase and unitary amplitude
resize(dimx, dimy[, pitch])	Resize the electric field
set_value(v)	Set new values for phase and amplitude
square_modulus(wavelengthInNm)	Compute the square modulus (intensity) of the electric field at a given wavelength.
sub_ef([xfrom, xto, yfrom, yto, idx])	Extract a subregion of the electric field.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

checkOther
from_header
get_fits_header
get_value
init_logging
masked_area
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

property A

area()

Calculate the area of the electric field.

array_for_display()

Returns a 2D array suitable for display: the phase (in nm) masked by the amplitude.

The returned array is the phase array (self.field[1]) where the amplitude (self.field[0]) is greater than zero. The average phase (over nonzero amplitude pixels) is subtracted for visualization purposes.

Returns:

frame – 2D array of phase values (in nm), mean-subtracted over nonzero amplitude pixels.

Return type:

xp.ndarray

checkOther(ef2, subrect=None)

compare(ef2)

Compare this ElectricField object with another ElectricField object.

Parameters:

ef2 (ElectricField) – The ElectricField object to compare with.

Returns:

True if the fields are different, False if they are equal.

Return type:

bool

ef_at_lambda(wavelengthInNm, slicey=None, slicex=None, out=None)

Calculate the electric field at a given wavelength.

Parameters:

• wavelengthInNm (float) – The wavelength in nanometers.

• slicey (slice, optional) – The slice along the y-axis (default: None, which means all rows).

• slicex (slice, optional) – The slice along the x-axis (default: None, which means all columns).

• out (xp.ndarray, optional) – The output array (default: None).

Returns:

The electric field at the given wavelength. If out is provided, the result is both stored in out and and the same reference is returned.

Return type:

xp.ndarray

static from_header(hdr, target_device_idx=None)

get_fits_header()

get_value()

masked_area()

property phaseInNm

phi_at_lambda(wavelengthInNm, slicey=None, slicex=None)

Calculate the phase of the electric field at a given wavelength.

Parameters:

• wavelengthInNm (float) – The wavelength in nanometers.

• slicey (slice, optional) – The slice along the y-axis (default: None, which means all rows).

• slicex (slice, optional) – The slice along the x-axis (default: None, which means all columns).

Returns:

The phase of the electric field at the given wavelength.

Return type:

xp.ndarray

product(ef2, subrect=None)

Multiply the electric field by another electric field.

Parameters:

• ef2 (ElectricField) – The other electric field.

• subrect (tuple, optional) – The subrectangle to multiply (top-left coordinate into ef2. Default: None, which means all of ef2).

reset()

Reset to zero phase and unitary amplitude

Arrays are not reallocated

resize(dimx, dimy, pitch=None)

Resize the electric field

The pixel pitch and S0 are not changed

static restore(filename, target_device_idx=None)

save(filename, overwrite=True)

set_value(v)

Set new values for phase and amplitude

Arrays are not reallocated

property size

square_modulus(wavelengthInNm)

Compute the square modulus (intensity) of the electric field at a given wavelength.

Parameters:

wavelengthInNm (float) – The wavelength in nanometers at which to compute the square modulus.

Returns:

The square modulus (intensity) of the electric field at the specified wavelength.

Return type:

xp.ndarray

sub_ef(xfrom=None, xto=None, yfrom=None, yto=None, idx=None)

Extract a subregion of the electric field.

Parameters:

• xfrom (int, optional) – Starting index along the x-axis (inclusive).

• xto (int, optional) – Ending index along the x-axis (exclusive).

• yfrom (int, optional) – Starting index along the y-axis (inclusive).

• yto (int, optional) – Ending index along the y-axis (exclusive).

• idx (array-like, optional) – Indices to extract as a subregion. If provided, xfrom/xto/yfrom/yto are ignored.

Returns:

A new ElectricField object representing the extracted subregion.

Return type:

ElectricField

Gaussian Convolution Kernel

class specula.data_objects.gaussian_convolution_kernel.GaussianConvolutionKernel(dimx: int, dimy: int, pxscale: float, dimension: int, spot_size: float, pupil_size_m: 0.0 = <class 'float'>, oversampling: int = 1, return_fft: bool = True, positive_shift_tt: bool = True, airmass: float = 1.0, data_dir: str = '', target_device_idx: int = None, precision: int = None)

Bases: ConvolutionKernel

Gaussian Convolution Kernel data object. This object stores a Gaussian convolution kernel for Shack-Hartmann wavefront sensing and performs the related computations.

Methods

build()	Recalculates the Gaussian kernel based on current settings.
calculate_lgs_map()	Calculate the LGS (Laser Guide Star) map based on current parameters.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
generate_hash(items)	Generate a hash for the current kernel settings.
get_value()	Get current kernels.
restore(filename[, target_device_idx, ...])	Restore a GaussianConvolutionKernel object from a FITS file.
save(filename)	Save the kernel to a FITS file.
set_value(v)	Set new kernels.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

calculate_focus
from_header
get_fits_header
init_logging
monitorMem
prepare_for_sh
printMemUsage
process_kernels
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a ConvolutionKernel object.

Methods

build()	Recalculates the Gaussian kernel based on current settings.
calculate_lgs_map()	Calculate the LGS (Laser Guide Star) map based on current parameters.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
generate_hash(items)	Generate a hash for the current kernel settings.
get_value()	Get current kernels.
restore(filename[, target_device_idx, ...])	Restore a GaussianConvolutionKernel object from a FITS file.
save(filename)	Save the kernel to a FITS file.
set_value(v)	Set new kernels.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

calculate_focus
from_header
get_fits_header
init_logging
monitorMem
prepare_for_sh
printMemUsage
process_kernels
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

build()

Recalculates the Gaussian kernel based on current settings.

calculate_lgs_map()

Calculate the LGS (Laser Guide Star) map based on current parameters. This creates convolution kernels for each subaperture.

static restore(filename, target_device_idx=None, kernel_obj=None, return_fft=False)

Restore a GaussianConvolutionKernel object from a FITS file.

Parameters:

• filename (str) – Path to the FITS file

• target_device_idx (int, optional) – Target device index for GPU processing

• return_fft (bool, optional) – Whether to return FFT of the kernel

Returns:

The restored ConvolutionKernel object

Return type:

GaussianConvolutionKernel

Ifunc

class specula.data_objects.ifunc.IFunc(ifunc=None, type_str: str = None, mask=None, npixels: int = None, nzern: int = None, obsratio: float = None, diaratio: float = None, start_mode: int = None, nmodes: int = None, n_act: int = None, circ_geom: bool = True, angle_offset: float = 0, do_mech_coupling: bool = False, coupling_coeffs: list = [0.31, 0.05], do_slaving: bool = False, slaving_thr: float = 0.1, idx_modes=None, target_device_idx=None, precision=None)

Bases: BaseDataObj

Influence functions data object. This class holds the influence function matrix and the corresponding mask. Influence functions data are stored as [modes, pixels].

Attributes:

idx_inf_func

influence_function

mask_inf_func

size

type

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
ifunc_2d_to_3d([normalize])	Convert a 2D influence function to a 3D array using a mask.
inverse([nmodes, remove_piston])	Return the pseudoinverse of the influence function.
set_value(v)	Set a new influence function.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

cut
from_header
get_fits_header
get_value
init_logging
monitorMem
nmodes
npoints
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize the base data object.

Parameters: target_device_idx: int, optional

device to be targeted for data storage. Set to -1 for CPU, to 0 for the first GPU device, 1 for the second GPU device, etc.

precision: int, optional

if None will use the global_precision, otherwise set to 0 for double, 1 for single

Attributes:

idx_inf_func

influence_function

mask_inf_func

size

type

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
ifunc_2d_to_3d([normalize])	Convert a 2D influence function to a 3D array using a mask.
inverse([nmodes, remove_piston])	Return the pseudoinverse of the influence function.
set_value(v)	Set a new influence function.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

cut
from_header
get_fits_header
get_value
init_logging
monitorMem
nmodes
npoints
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

cut(start_mode=None, nmodes=None, idx_modes=None)

static from_header(hdr)

get_fits_header()

get_value()

property idx_inf_func

ifunc_2d_to_3d(normalize=True)

Convert a 2D influence function to a 3D array using a mask.

property influence_function

inverse(nmodes=None, remove_piston=True)

Return the pseudoinverse of the influence function.

When remove_piston is True, each mode is centered by subtracting its mean value before computing the pseudoinverse.

property mask_inf_func

nmodes()

npoints()

static restore(filename, target_device_idx=None, exten=1)

save(filename, overwrite=False)

set_value(v)

Set a new influence function. Arrays are not reallocated.

property size

property type

specula.data_objects.ifunc.compute_kl_ifunc(*args, **kwargs)

specula.data_objects.ifunc.compute_mixed_ifunc(*args, **kwargs)

Ifunc Inv

class specula.data_objects.ifunc_inv.IFuncInv(ifunc_inv, mask, target_device_idx=None, precision=None)

Bases: BaseDataObj

Inverse Influence Function data object. This class holds the inverse influence function matrix and the corresponding mask. Inverse influence functions data are stored as [pixels, modes].

Attributes:

size

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
cut([start_mode, nmodes, idx_modes])	Cut the inverse influence function to a subset of modes.
set_value(v)	Set a new influence function.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
get_value
init_logging
monitorMem
nmodes
npoints
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize an IFuncInv object.

Note

The inverse influence function is used to compute a modal/zonal vector from a wavefront.

Attributes:

size

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
cut([start_mode, nmodes, idx_modes])	Cut the inverse influence function to a subset of modes.
set_value(v)	Set a new influence function.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
get_value
init_logging
monitorMem
nmodes
npoints
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

cut(start_mode=None, nmodes=None, idx_modes=None)

Cut the inverse influence function to a subset of modes.

Parameters:

• start_mode (int, optional) – Starting mode index (default: 0)

• nmodes (int, optional) – Number of modes to keep (default: all remaining modes from start_mode)

• idx_modes (array-like, optional) – Explicit list of mode indices to keep. If provided, start_mode and nmodes are ignored.

Notes

The inverse influence function has shape (npixels, nmodes), so we cut along axis 1 (columns). This is the opposite of IFunc which has shape (nmodes, npixels) and cuts along axis 0 (rows).

static from_header(hdr)

get_fits_header()

get_value()

nmodes()

npoints()

static restore(filename, target_device_idx=None, exten=1)

save(filename, overwrite=False)

set_value(v)

Set a new influence function. Arrays are not reallocated.

property size

specula.data_objects.ifunc_inv.cut_modes(matrix, start_mode=None, nmodes=None, idx_modes=None, modes_on_first_axis=True)

Cut the an influence function (or an inverse one) to a subset of modes.

Parameters:

• matrix (array-like) – The matrix to cut. Shape should be (nmodes, npixels) for

• start_mode (int, optional) – Starting mode index (default: 0)

• nmodes (int, optional) – Number of modes to keep (default: all remaining modes from start_mode)

• idx_modes (array-like, optional) – Explicit list of mode indices to keep. If provided, start_mode and nmodes are ignored.

• modes_on_first_axis (bool, optional) – Whether the modes are on the first axis (rows) or second axis (columns) of the input array (default: True). For IFunc, modes are on the first axis. For IFuncInv, modes are on the second axis.

Iir Filter Data

class specula.data_objects.iir_filter_data.IirFilterData(ordnum: list, ordden: list, num, den, n_modes=None, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Infinite Impulse Response (IIR) Filter Data object. This class stores IIR filter coefficients and provides methods to analyze the filter’s transfer function, frequency response and stability.

Attributes:

has_control_support

Check if control library support is available.

nfilter

Methods

NTF(mode, fs[, freq, dm, nw, dw, title, ...])	Plot Noise Transfer Function: NTF = CP / (1 + CP)
RTF(mode, fs[, freq, dm, nw, dw, title, ...])	Plot Rejection Transfer Function: RTF = 1 / (1 + CP)
bode_plot([mode, dt, omega, plot])	Create Bode plot for a specific filter using control library.
closed_loop_denominator(c_num, c_den, p_num, ...)	Calculate closed-loop denominator for feedback system given numerator and denominator of control and plant.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
discrete_delay_tf(delay)	Generate transfer function for discrete delay.
frequency_response(num, den, fs[, freq])	Compute complex frequency response of IIR filter.
from_control_tf(tf_list[, target_device_idx])	Create IirFilterData from control.TransferFunction objects.
from_gain_and_ff(gain[, ff, target_device_idx])	Build an IirFilterData object from a gain value/vector and an optional forgetting factor value/vector
impulse_response([mode, dt, T])	Compute impulse response for a specific filter using control library.
is_stable(mode[, dm, nw, dw])	Check stability by analyzing poles of the closed-loop system.
lpf_from_fc(fc, fs[, n_ord, target_device_idx])	Build an IirFilterData object from a cut off frequency value/vector and a filter order value (must be even)
lpf_from_fc_and_ampl(fc, ampl, fs[, ...])	Build an IirFilterData object from a cut off frequency value/vector and amplification value/vector
max_stable_gain([mode, delay, dm, nw, dw, ...])	Calculate maximum stable gain for closed-loop system.
nyquist_plot([mode, dt, omega, plot])	Create Nyquist plot for a specific filter using control library.
pole_zero_map([mode, dt, plot])	Create pole-zero map for a specific filter using control library.
resonance_frequency(mode[, gain_factor, ...])	Calculate resonance frequency of closed-loop system.
stability_analysis([mode, delay, dm, nw, ...])	Comprehensive stability analysis for controller(s).
stability_margins([mode, dt])	Compute stability margins for a specific filter using control library.
step_response([mode, dt, T])	Compute step response for a specific filter using control library.
to_control_tf([mode, dt])	Convert a single filter to a control.TransferFunction object.
to_control_tf_list([dt])	Convert all filters to a list of control.TransferFunction objects.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
get_poles
get_value
get_zeros
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
set_den
set_gain
set_num
set_poles
set_value
set_zeros
startMemUsageCount
stopMemUsageCount
t_to_seconds

IirFilterData - IIR Filter Data representation.

This class stores IIR filter coefficients in the following format: - Coefficients are stored with lowest order terms first - num[i, :] contains numerator coefficients for filter i - den[i, :] contains denominator coefficients for filter i - ordnum[i] and ordden[i] specify the actual order of each filter

Transfer function: H(z) = (num[0] + num[1]*z + …) / (den[0] + den[1]*z + …)

Attributes:

has_control_support

Check if control library support is available.

nfilter

Methods

NTF(mode, fs[, freq, dm, nw, dw, title, ...])	Plot Noise Transfer Function: NTF = CP / (1 + CP)
RTF(mode, fs[, freq, dm, nw, dw, title, ...])	Plot Rejection Transfer Function: RTF = 1 / (1 + CP)
bode_plot([mode, dt, omega, plot])	Create Bode plot for a specific filter using control library.
closed_loop_denominator(c_num, c_den, p_num, ...)	Calculate closed-loop denominator for feedback system given numerator and denominator of control and plant.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
discrete_delay_tf(delay)	Generate transfer function for discrete delay.
frequency_response(num, den, fs[, freq])	Compute complex frequency response of IIR filter.
from_control_tf(tf_list[, target_device_idx])	Create IirFilterData from control.TransferFunction objects.
from_gain_and_ff(gain[, ff, target_device_idx])	Build an IirFilterData object from a gain value/vector and an optional forgetting factor value/vector
impulse_response([mode, dt, T])	Compute impulse response for a specific filter using control library.
is_stable(mode[, dm, nw, dw])	Check stability by analyzing poles of the closed-loop system.
lpf_from_fc(fc, fs[, n_ord, target_device_idx])	Build an IirFilterData object from a cut off frequency value/vector and a filter order value (must be even)
lpf_from_fc_and_ampl(fc, ampl, fs[, ...])	Build an IirFilterData object from a cut off frequency value/vector and amplification value/vector
max_stable_gain([mode, delay, dm, nw, dw, ...])	Calculate maximum stable gain for closed-loop system.
nyquist_plot([mode, dt, omega, plot])	Create Nyquist plot for a specific filter using control library.
pole_zero_map([mode, dt, plot])	Create pole-zero map for a specific filter using control library.
resonance_frequency(mode[, gain_factor, ...])	Calculate resonance frequency of closed-loop system.
stability_analysis([mode, delay, dm, nw, ...])	Comprehensive stability analysis for controller(s).
stability_margins([mode, dt])	Compute stability margins for a specific filter using control library.
step_response([mode, dt, T])	Compute step response for a specific filter using control library.
to_control_tf([mode, dt])	Convert a single filter to a control.TransferFunction object.
to_control_tf_list([dt])	Convert all filters to a list of control.TransferFunction objects.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
get_poles
get_value
get_zeros
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
set_den
set_gain
set_num
set_poles
set_value
set_zeros
startMemUsageCount
stopMemUsageCount
t_to_seconds

NTF(mode, fs, freq=None, dm=None, nw=None, dw=None, title=None, plot=True, overplot=False, **extra)

Plot Noise Transfer Function: NTF = CP / (1 + CP)

Parameters:

• mode – Filter mode index to use for C coefficients

• fs – Sampling frequency

• freq – Frequency vector for evaluation (if None, auto-generated)

• dm – Optional plant parameters to construct P The plant is represented as P = nw / (dm * dw)

• nw – Optional plant parameters to construct P The plant is represented as P = nw / (dm * dw)

• dw – Optional plant parameters to construct P The plant is represented as P = nw / (dm * dw)

• title – Title for the plot

• plot – If True, generate the plot

• overplot – If True, plot on existing figure instead of creating new one

• **extra – Additional plotting parameters (e.g., color)

Returns:

Magnitude of the Noise Transfer Function at specified frequencies

Return type:

ntf_mag

RTF(mode, fs, freq=None, dm=None, nw=None, dw=None, title=None, plot=True, overplot=False, **extra)

Plot Rejection Transfer Function: RTF = 1 / (1 + CP)

Parameters:

• mode – Filter mode index to use for C coefficients

• fs – Sampling frequency

• freq – Frequency vector for evaluation (if None, auto-generated)

• dm – Optional plant parameters to construct P The plant is represented as P = nw / (dm * dw)

• nw – Optional plant parameters to construct P The plant is represented as P = nw / (dm * dw)

• dw – Optional plant parameters to construct P The plant is represented as P = nw / (dm * dw)

• title – Title for the plot

• plot – If True, generate the plot

• overplot – If True, plot on existing figure instead of creating new one

• **extra – Additional plotting parameters (e.g., color)

Returns:

Magnitude of the Rejection Transfer Function at specified frequencies

Return type:

rtf_mag

bode_plot(mode: int = 0, dt: float = None, omega: ndarray = None, plot: bool = True, **kwargs)

Create Bode plot for a specific filter using control library.

Parameters:

• mode – Index of the filter to plot (default: 0)

• dt – Sampling time for discrete-time system (default: None)

• omega – Frequency vector (default: auto-generated)

• plot – Whether to display the plot (default: True)

• **kwargs – Additional arguments passed to control.bode_plot

Returns:

(magnitude, phase, frequency) arrays or ControlPlot object

Return type:

tuple

Raises:

ImportError – If control library is not installed

closed_loop_denominator(c_num, c_den, p_num, p_den)

Calculate closed-loop denominator for feedback system given numerator and denominator of control and plant.

discrete_delay_tf(delay)

Generate transfer function for discrete delay.

If not-integer delay TF: DelayTF = z^(−l) * ( m * (1−z^(−1)) + z^(−1) ) where delay = (l+1)*T − mT, T integration time, l integer, 0<m<1

Parameters:

delay – Delay value (can be fractional)

Returns:

(num, den) - numerator and denominator coefficients

Return type:

tuple

frequency_response(num, den, fs, freq=None)

Compute complex frequency response of IIR filter.

Parameters:

• num – Numerator coefficients

• den – Denominator coefficients

• fs – Sampling frequency

• freq – Frequency vector (if None, auto-generated)

Returns:

Complex frequency response values at specified frequencies

static from_control_tf(tf_list, target_device_idx: int = None)

Create IirFilterData from control.TransferFunction objects.

Parameters:

• tf_list – Single control.TransferFunction or list of control.TransferFunction objects

• target_device_idx – Target device index (default: None)

Returns:

New IirFilterData object

Return type:

IirFilterData

static from_gain_and_ff(gain, ff=None, target_device_idx=None)

Build an IirFilterData object from a gain value/vector and an optional forgetting factor value/vector

static from_header(hdr)

get_fits_header()

get_poles()

get_value()

get_zeros()

property has_control_support

Check if control library support is available.

impulse_response(mode: int = 0, dt: float = None, T: ndarray = None, **kwargs)

Compute impulse response for a specific filter using control library.

Parameters:

• mode – Index of the filter (default: 0)

• dt – Sampling time for discrete-time system (default: None)

• T – Time vector (default: auto-generated)

• **kwargs – Additional arguments passed to control.impulse_response

Returns:

(time, response) arrays

Return type:

tuple

Raises:

ImportError – If control library is not installed

is_stable(mode, dm=None, nw=None, dw=None)

Check stability by analyzing poles of the closed-loop system.

Parameters:

• mode – Filter mode index

• dm – Plant coefficients (optional)

• nw – Plant coefficients (optional)

• dw – Plant coefficients (optional)

Returns:

True if stable, False otherwise

Return type:

bool

static lpf_from_fc(fc, fs, n_ord=2, target_device_idx=None)

Build an IirFilterData object from a cut off frequency value/vector and a filter order value (must be even)

static lpf_from_fc_and_ampl(fc, ampl, fs, target_device_idx=None)

Build an IirFilterData object from a cut off frequency value/vector and amplification value/vector

max_stable_gain(mode=None, delay=None, dm=None, nw=None, dw=None, max_gain=20.0, n_gain=10000, tolerance=1e-06)

Calculate maximum stable gain for closed-loop system.

This function finds the maximum controller gain that maintains stability in a closed-loop system with the given plant dynamics.

Parameters:

• mode – Filter mode index. If None, calculates for all modes

• delay – Delay in frames (alternative to dm/nw/dw)

• dm – Plant coefficients (alternative to delay)

• nw – Plant coefficients (alternative to delay)

• dw – Plant coefficients (alternative to delay)

• max_gain – Maximum gain to test (default: 20.0)

• n_gain – Number of gain values to test (default: 10000)

• tolerance – Minimum gain to test (default: 1e-6)

Returns:

Maximum stable gain(s)

Return type:

float or array

Examples

# Single mode with delay max_gain = filter_data.max_stable_gain(mode=0, delay=2.5)

# All modes with plant dynamics max_gains = filter_data.max_stable_gain(dm=dm_coeffs, nw=nw_coeffs, dw=dw_coeffs)

# All modes with delay (useful for integrator-based controllers) max_gains = filter_data.max_stable_gain(delay=1.0)

property nfilter

nyquist_plot(mode: int = 0, dt: float = None, omega: ndarray = None, plot: bool = True, **kwargs)

Create Nyquist plot for a specific filter using control library.

Parameters:

• mode – Index of the filter to plot (default: 0)

• dt – Sampling time for discrete-time system (default: None)

• omega – Frequency vector (default: auto-generated)

• plot – Whether to display the plot (default: True)

• **kwargs – Additional arguments passed to control.nyquist_plot

Returns:

(real, imaginary, frequency) arrays or ControlPlot object

Return type:

tuple

Raises:

ImportError – If control library is not installed

pole_zero_map(mode: int = 0, dt: float = None, plot: bool = True, **kwargs)

Create pole-zero map for a specific filter using control library.

Parameters:

• mode – Index of the filter (default: 0)

• dt – Sampling time for discrete-time system (default: None)

• plot – Whether to display the plot (default: True)

• **kwargs – Additional arguments passed to control.pzmap

Returns:

(poles, zeros) arrays

Return type:

tuple

Raises:

ImportError – If control library is not installed

resonance_frequency(mode, gain_factor=1.0, delay=None, dm=None, nw=None, dw=None, fs=1000.0, freq=None)

Calculate resonance frequency of closed-loop system.

Parameters:

• mode – Filter mode index

• gain_factor – Factor to multiply the filter gain (default: 1.0)

• delay – Delay in frames (alternative to dm/nw/dw)

• dm – Plant coefficients (alternative to delay)

• nw – Plant coefficients (alternative to delay)

• dw – Plant coefficients (alternative to delay)

• fs – Sampling frequency in Hz (default: 1000.0)

• freq – Frequency vector for analysis (default: auto-generated)

Returns:

(resonance_frequency, resonance_amplitude)

Return type:

tuple

static restore(filename, target_device_idx=None)

save(filename)

set_den(den)

set_gain(gain)

set_num(num)

set_poles(poles)

set_value(v)

set_zeros(zeros)

stability_analysis(mode=None, delay=None, dm=None, nw=None, dw=None, fs=1000.0, max_gain=20.0, n_gain=10000)

Comprehensive stability analysis for controller(s).

Parameters:

• mode – Filter mode index. If None, analyzes all modes

• delay – Delay in frames (alternative to dm/nw/dw)

• dm – Plant coefficients (alternative to delay)

• nw – Plant coefficients (alternative to delay)

• dw – Plant coefficients (alternative to delay)

• fs – Sampling frequency in Hz (default: 1000.0)

• max_gain – Maximum gain to test (default: 20.0)

• n_gain – Number of gain values to test (default: 10000)

Returns:

Analysis results containing max_stable_gain, resonance_freq, etc.

Return type:

dict

stability_margins(mode: int = 0, dt: float = None)

Compute stability margins for a specific filter using control library.

Parameters:

• mode – Index of the filter (default: 0)

• dt – Sampling time for discrete-time system (default: None)

Returns:

(gain_margin, phase_margin, wg, wp) where:

• gain_margin: Gain margin in dB

• phase_margin: Phase margin in degrees

• wg: Frequency at gain margin

• wp: Frequency at phase margin

Return type:

tuple

Raises:

ImportError – If control library is not installed

step_response(mode: int = 0, dt: float = None, T: ndarray = None, **kwargs)

Compute step response for a specific filter using control library.

Parameters:

• mode – Index of the filter (default: 0)

• dt – Sampling time for discrete-time system (default: None)

• T – Time vector (default: auto-generated)

• **kwargs – Additional arguments passed to control.step_response

Returns:

(time, response) arrays

Return type:

tuple

Raises:

ImportError – If control library is not installed

to_control_tf(mode: int = 0, dt: float = None)

Convert a single filter to a control.TransferFunction object.

Parameters:

• mode – Index of the filter to convert (default: 0)

• dt – Sampling time for discrete-time system (default: None for continuous-time)

Returns:

The transfer function object

Return type:

control.TransferFunction

Raises:

ImportError – If control library is not installed

to_control_tf_list(dt: float = None)

Convert all filters to a list of control.TransferFunction objects.

Parameters:

dt – Sampling time for discrete-time system (default: None for continuous-time)

Returns:

List of control.TransferFunction objects

Return type:

list

Raises:

ImportError – If control library is not installed

Infinite Phase Screen

class specula.data_objects.infinite_phase_screen.InfinitePhaseScreen(mx_size, pixel_scale, r0, L0, random_seed=None, stencil_size_factor=1, xp=None, target_device_idx=None, precision=None)

Bases: BaseDataObj

Infinite Phase Screen Data object. This class generates and holds an infinite phase screen generated using a stochastic process that simulates atmospheric turbulence.

Attributes:

scrn

scrnRaw

scrnRawAll

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

AB_from_positions
add_line
get_new_line
init_logging
monitorMem
phase_covariance
prepare_random_data_col
prepare_random_data_row
printMemUsage
seconds_to_t
set_stencil_coords
set_stencil_coords_basic
setup
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize the base data object.

Parameters: target_device_idx: int, optional

device to be targeted for data storage. Set to -1 for CPU, to 0 for the first GPU device, 1 for the second GPU device, etc.

precision: int, optional

if None will use the global_precision, otherwise set to 0 for double, 1 for single

Attributes:

scrn

scrnRaw

scrnRawAll

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

AB_from_positions
add_line
get_new_line
init_logging
monitorMem
phase_covariance
prepare_random_data_col
prepare_random_data_row
printMemUsage
seconds_to_t
set_stencil_coords
set_stencil_coords_basic
setup
startMemUsageCount
stopMemUsageCount
t_to_seconds

AB_from_positions(positions)

add_line(row, after, flush=True)

get_new_line(row, after)

phase_covariance(r, r0, L0)

prepare_random_data_col()

prepare_random_data_row()

property scrn

property scrnRaw

property scrnRawAll

set_stencil_coords()

set_stencil_coords_basic()

setup()

specula.data_objects.infinite_phase_screen.cn2_to_r0(cn2, wvl=5e-07)

specula.data_objects.infinite_phase_screen.cn2_to_seeing(cn2, wvl=5e-07)

specula.data_objects.infinite_phase_screen.r0_to_seeing(r0, wvl=5e-07)

specula.data_objects.infinite_phase_screen.seeing_to_r0(seeing, wvl=5e-07)

Intensity

class specula.data_objects.intensity.Intensity(dimx: int, dimy: int, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Intensity field data object.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the intensity field as a numpy/cupy array
set_value(v)	Set new values for the intensity field Arrays are not reallocated
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

array_for_display
from_header
get_fits_header
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
sum
t_to_seconds

Initialize an Intensity object.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the intensity field as a numpy/cupy array
set_value(v)	Set new values for the intensity field Arrays are not reallocated
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

array_for_display
from_header
get_fits_header
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
sum
t_to_seconds

array_for_display()

static from_header(hdr, target_device_idx=None)

get_fits_header()

get_value()

Get the intensity field as a numpy/cupy array

static restore(filename, target_device_idx=None)

save(filename, overwrite=True)

set_value(v)

Set new values for the intensity field Arrays are not reallocated

sum(i2, factor=1.0)

Intmat

class specula.data_objects.intmat.Intmat(intmat=None, nmodes: int = None, nslopes: int = None, slope_mm: list = None, slope_rms: list = None, pupdata_tag: str = '', subapdata_tag: str = '', norm_factor: float = 0.0, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Interaction matrix data object. This class holds the interaction matrix (intmat) and related metadata for wavefront reconstruction.

Attributes:

nmodes

nslopes

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the intmat as a numpy/cupy array
set_value(v)	Set new values for the intmat Arrays are not reallocated
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

build_from_slopes
from_header
generate_rec
generate_rec_mmse
get_fits_header
init_logging
monitorMem
printMemUsage
pseudo_invert
reduce_size
reduce_slopes
restore
save
seconds_to_t
set_nmodes
set_nslopes
set_start_mode
startMemUsageCount
stopMemUsageCount
t_to_seconds

Note

axes are [slopes, modes]

Members .modes and .slopes allow numpy-like access, for example:

intmat_obj.modes[3:5] += 1

Attributes:

nmodes

nslopes

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the intmat as a numpy/cupy array
set_value(v)	Set new values for the intmat Arrays are not reallocated
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

build_from_slopes
from_header
generate_rec
generate_rec_mmse
get_fits_header
init_logging
monitorMem
printMemUsage
pseudo_invert
reduce_size
reduce_slopes
restore
save
seconds_to_t
set_nmodes
set_nslopes
set_start_mode
startMemUsageCount
stopMemUsageCount
t_to_seconds

static build_from_slopes(slopes, disturbance, target_device_idx=None)

static from_header(hdr, target_device_idx=None)

generate_rec(nmodes=None, cut_modes=0, w_vec=None, interactive=False)

generate_rec_mmse(r0, L0, diameter, modal_base, c_noise, nmodes=None, m2c=None)

get_fits_header()

get_value()

Get the intmat as a numpy/cupy array

property nmodes

property nslopes

pseudo_invert(matrix, n_modes_to_drop=0, w_vec=None, interactive=False)

reduce_size(n_modes_to_be_discarded)

reduce_slopes(n_slopes_to_be_discarded)

static restore(filename, target_device_idx=None)

save(filename, overwrite=True)

set_nmodes(new_nmodes)

set_nslopes(new_nslopes)

set_start_mode(start_mode)

set_value(v)

Set new values for the intmat Arrays are not reallocated

Laser Launch Telescope

class specula.data_objects.laser_launch_telescope.LaserLaunchTelescope(simul_params: SimulParams = None, spot_size: float = 0.0, tel_position: list = [], beacon_focus: float = 90000.0, beacon_tt: list = [0.0, 0.0], target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Laser Launch Telescope data object. This class holds the parameters of the laser launch telescope, such as spot size, position, focus and tilt.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
get_value
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

Parameters:

• simul_params (SimulParams) – The simulation parameters object, required to get the zenith angle.

• spot_size (float [arcsec]) – The size of the laser spot.

• tel_position (list [m]) – The x, y and z position of the launch telescope w.r.t. the telescope.

• beacon_focus (float [m]) – The distance from the telescope pupil to beacon focus.

• beacon_tt (list [arcsec]) – The tilt and tip of the beacon.

• significant (TODO the empty tel_position array is actually) – it is checked in the SH code to manage the kernels, but gives some problems for the FITS header (when reading from disk, it won’t be empty anymore)

• because – it is checked in the SH code to manage the kernels, but gives some problems for the FITS header (when reading from disk, it won’t be empty anymore)

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
get_value
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

static from_header(hdr, target_device_idx=None)

get_fits_header()

get_value()

static restore(filename, target_device_idx=None)

save(filename, overwrite=False)

set_value(v)

Layer

class specula.data_objects.layer.Layer(dimx: int, dimy: int, pixel_pitch: float, height: float, shiftXYinPixel: tuple = (0.0, 0.0), rotInDeg: float = 0.0, magnification: float = 1.0, target_device_idx: int = None, precision: int = None)

Bases: ElectricField

Layer data object. This object represents a layer in the atmosphere for wavefront propagation simulations. It inherits from the ElectricField class and adds additional properties such as height, shifts, rotation, and magnification.

Attributes:

A

phaseInNm

size

Methods

area()	Calculate the area of the electric field.
array_for_display()	Returns a 2D array suitable for display: the phase (in nm) masked by the amplitude.
compare(ef2)	Compare this ElectricField object with another ElectricField object.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
ef_at_lambda(wavelengthInNm[, slicey, ...])	Calculate the electric field at a given wavelength.
phi_at_lambda(wavelengthInNm[, slicey, slicex])	Calculate the phase of the electric field at a given wavelength.
product(ef2[, subrect])	Multiply the electric field by another electric field.
reset()	Reset to zero phase and unitary amplitude
resize(dimx, dimy[, pitch])	Resize the electric field
set_value(v)	Set new values for phase and amplitude
square_modulus(wavelengthInNm)	Compute the square modulus (intensity) of the electric field at a given wavelength.
sub_ef([xfrom, xto, yfrom, yto, idx])	Extract a subregion of the electric field.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

checkOther
from_header
get_fits_header
get_value
init_logging
masked_area
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a Layer object.

Parameters:

• dimx (int [pixels]) – Number of pixels along the x-axis (width).

• dimy (int [pixels]) – Number of pixels along the y-axis (height).

• pixel_pitch (float [m]) – The dimension in meters of a pixel.

• height (float [m]) – The height of the layer.

• shiftXYinPixel (tuple [pixels], optional) – The (x, y) shift of the layer in pixel units (default: (0.0, 0.0)).

• rotInDeg (float [deg], optional) – The rotation of the layer in degrees (default: 0.0).

• magnification (float [1], optional) – The magnification factor of the layer (default: 1.0).

• target_device_idx (int [1], optional) – Device index for computation (default: None).

• precision (int [1], optional) – Precision for computation (default: None).

Attributes:

A

phaseInNm

size

Methods

area()	Calculate the area of the electric field.
array_for_display()	Returns a 2D array suitable for display: the phase (in nm) masked by the amplitude.
compare(ef2)	Compare this ElectricField object with another ElectricField object.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
ef_at_lambda(wavelengthInNm[, slicey, ...])	Calculate the electric field at a given wavelength.
phi_at_lambda(wavelengthInNm[, slicey, slicex])	Calculate the phase of the electric field at a given wavelength.
product(ef2[, subrect])	Multiply the electric field by another electric field.
reset()	Reset to zero phase and unitary amplitude
resize(dimx, dimy[, pitch])	Resize the electric field
set_value(v)	Set new values for phase and amplitude
square_modulus(wavelengthInNm)	Compute the square modulus (intensity) of the electric field at a given wavelength.
sub_ef([xfrom, xto, yfrom, yto, idx])	Extract a subregion of the electric field.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

checkOther
from_header
get_fits_header
get_value
init_logging
masked_area
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

static from_header(hdr, target_device_idx=None)

get_fits_header()

static restore(filename, target_device_idx=None)

save(filename, overwrite=True)

Lenslet

class specula.data_objects.lenslet.Lenslet(n_lenses: int = 1, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Lenslet data object. This class holds the information about the lenslet array, such as the number of lenses and their positions.

Attributes:

dimx

dimy

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get(x, y)	Returns the subaperture information at (x, y)
get_value()
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a Lenslet object.

Parameters:

• n_lenses (int [1]) – The number of lenses in the lenslet array (default: 1).

• target_device_idx (int [1], optional) – Device index for computation (default: None).

• precision (int [1], optional) – Precision for computation (default: None).

Attributes:

dimx

dimy

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get(x, y)	Returns the subaperture information at (x, y)
get_value()
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

property dimx

property dimy

static from_header(hdr, target_device_idx=None)

get(x, y)

Returns the subaperture information at (x, y)

get_fits_header()

get_value()

static restore(filename, target_device_idx=None)

save(filename, overwrite=False)

set_value(v)

M2C

class specula.data_objects.m2c.M2C(m2c, nmodes: int = None, norm_factor: float = None, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Modal to Command (M2C) matrix data object. This class holds the M2C matrix, which is used to convert modal coefficients to actuator commands. The M2C matrix is stored as [actuators, modes].

Attributes:

nmodes

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the m2c matrix field as a numpy/cupy array
restore(filename[, target_device_idx])	Restores the M2C from a file.
save(filename[, overwrite])	Saves the M2C to a file.
set_value(v)	Set new values for the m2c matrix field Arrays are not reallocated
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

cut
from_header
get_fits_header
init_logging
monitorMem
printMemUsage
seconds_to_t
set_nmodes
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a M2C object.

Attributes:

nmodes

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the m2c matrix field as a numpy/cupy array
restore(filename[, target_device_idx])	Restores the M2C from a file.
save(filename[, overwrite])	Saves the M2C to a file.
set_value(v)	Set new values for the m2c matrix field Arrays are not reallocated
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

cut
from_header
get_fits_header
init_logging
monitorMem
printMemUsage
seconds_to_t
set_nmodes
startMemUsageCount
stopMemUsageCount
t_to_seconds

cut(start_mode=None, nmodes=None, idx_modes=None)

static from_header(hdr, target_device_idx=None)

get_fits_header()

get_value()

Get the m2c matrix field as a numpy/cupy array

property nmodes

static restore(filename, target_device_idx=None)

Restores the M2C from a file.

save(filename, overwrite: bool = False)

Saves the M2C to a file.

set_nmodes(nmodes)

set_value(v)

Set new values for the m2c matrix field Arrays are not reallocated

Pixels

class specula.data_objects.pixels.Pixels(dimx: int, dimy: int, bits: int = 16, signed: int = 0, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Pixels data object. Holds a 2d array of pixels, which can be signed or unsigned. The number of bits per pixel can be set, up to 64 bits.

Attributes:

size

Get the shape of the pixels array.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the pixel values as a numpy/cupy array
multiply(factor)	Multiply the pixels by a factor.
resize(dimx, dimy[, bits, signed])	Resize the pixels array to new dimensions and optionally change the bits and signedness.
set_size(size)	Set a new shape of the pixels array, discarding the old values.
set_value(v)	Set new pixel values.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

array_for_display
from_header
get_fits_header
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a Pixels data object.

Parameters:

• dimx (int [pixels]) – Number of pixels along the x-axis (width)

• dimy (int [pixels]) – Number of pixels along the y-axis (height)

• bits (int [1], optional) – Number of bits per pixel (default: 16).

• signed (int [1], optional) – 0 for unsigned, 1 for signed pixel values (default: 0).

• target_device_idx (int [1], optional) – Device index for computation (default: None).

• precision (int [1], optional) – Precision for computation (default: None).

Attributes:

size

Get the shape of the pixels array.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the pixel values as a numpy/cupy array
multiply(factor)	Multiply the pixels by a factor.
resize(dimx, dimy[, bits, signed])	Resize the pixels array to new dimensions and optionally change the bits and signedness.
set_size(size)	Set a new shape of the pixels array, discarding the old values.
set_value(v)	Set new pixel values.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

array_for_display
from_header
get_fits_header
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

array_for_display()

static from_header(hdr, target_device_idx=None)

get_fits_header()

get_value()

Get the pixel values as a numpy/cupy array

multiply(factor)

Multiply the pixels by a factor.

resize(dimx: int, dimy: int, bits=16, signed=0)

Resize the pixels array to new dimensions and optionally change the bits and signedness.

static restore(filename, target_device_idx=None)

save(filename, overwrite=True)

set_size(size)

Set a new shape of the pixels array, discarding the old values.

set_value(v)

Set new pixel values. Arrays are not reallocated.

property size

Get the shape of the pixels array.

Pupdata

class specula.data_objects.pupdata.PupData(ind_pup=None, radius=None, cx=None, cy=None, framesize=None, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Pupil data object. This class holds the information about the pupils of a Pyramid WFS (or a Zernike WFS). PupData includes an ind_pup array with the pixel indexes of each pupil, of shape [index, pupil].

Attributes:

display_map

n_pupils

n_subap

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the pixel values as a numpy/cupy array
restore(filename[, target_device_idx])	Restores the pupil data from a file.
set_value(v)	Set new ind_pup values.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

complete_mask
from_header
get_fits_header
init_logging
monitorMem
printMemUsage
pupil_idx
save
seconds_to_t
set_slopes_from_intensity
single_mask
startMemUsageCount
stopMemUsageCount
t_to_seconds
zcorrection

Note

TODO change by passing all the initializing arguments as __init__ parameters, to avoid the later initialization (see test/test_slopec.py for an example), where things can be forgotten easily.

Attributes:

display_map

n_pupils

n_subap

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the pixel values as a numpy/cupy array
restore(filename[, target_device_idx])	Restores the pupil data from a file.
set_value(v)	Set new ind_pup values.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

complete_mask
from_header
get_fits_header
init_logging
monitorMem
printMemUsage
pupil_idx
save
seconds_to_t
set_slopes_from_intensity
single_mask
startMemUsageCount
stopMemUsageCount
t_to_seconds
zcorrection

complete_mask()

property display_map

static from_header(filename, target_device_idx=None)

get_fits_header()

get_value()

Get the pixel values as a numpy/cupy array

property n_pupils

property n_subap

pupil_idx(n)

static restore(filename, target_device_idx=None)

Restores the pupil data from a file.

save(filename, overwrite=False)

set_slopes_from_intensity(value: bool = True)

set_value(v)

Set new ind_pup values. Arrays are not reallocated.

single_mask()

zcorrection(indpup)

Pupilstop

class specula.data_objects.pupilstop.Pupilstop(simul_params: SimulParams, input_mask=None, mask_diam: float = 1.0, obs_diam: float = None, shiftXYinPixel: tuple = (0.0, 0.0), rotInDeg: float = 0.0, magnification: float = 1.0, target_device_idx: int = None, precision: int = None)

Bases: Layer

Pupil stop data object. This class holds the information about the pupil stop, i.e. the amplitude mask in the pupil plane.

Attributes:

A

phaseInNm

size

Methods

area()	Calculate the area of the electric field.
array_for_display()	Returns a 2D array suitable for display: the phase (in nm) masked by the amplitude.
compare(ef2)	Compare this ElectricField object with another ElectricField object.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
ef_at_lambda(wavelengthInNm[, slicey, ...])	Calculate the electric field at a given wavelength.
get_value()	Get the amplitude mask as a numpy/cupy array
phi_at_lambda(wavelengthInNm[, slicey, slicex])	Calculate the phase of the electric field at a given wavelength.
product(ef2[, subrect])	Multiply the electric field by another electric field.
reset()	Reset to zero phase and unitary amplitude
resize(dimx, dimy[, pitch])	Resize the electric field
restore_from_passata(filename[, ...])	Restore a Pupilstop object from a PASSATA format file.
set_value(v)	Set a new amplitude mask.
square_modulus(wavelengthInNm)	Compute the square modulus (intensity) of the electric field at a given wavelength.
sub_ef([xfrom, xto, yfrom, yto, idx])	Extract a subregion of the electric field.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

checkOther
from_header
get_fits_header
init_logging
masked_area
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a Layer object.

Parameters:

• dimx (int [pixels]) – Number of pixels along the x-axis (width).

• dimy (int [pixels]) – Number of pixels along the y-axis (height).

• pixel_pitch (float [m]) – The dimension in meters of a pixel.

• height (float [m]) – The height of the layer.

• shiftXYinPixel (tuple [pixels], optional) – The (x, y) shift of the layer in pixel units (default: (0.0, 0.0)).

• rotInDeg (float [deg], optional) – The rotation of the layer in degrees (default: 0.0).

• magnification (float [1], optional) – The magnification factor of the layer (default: 1.0).

• target_device_idx (int [1], optional) – Device index for computation (default: None).

• precision (int [1], optional) – Precision for computation (default: None).

Attributes:

A

phaseInNm

size

Methods

area()	Calculate the area of the electric field.
array_for_display()	Returns a 2D array suitable for display: the phase (in nm) masked by the amplitude.
compare(ef2)	Compare this ElectricField object with another ElectricField object.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
ef_at_lambda(wavelengthInNm[, slicey, ...])	Calculate the electric field at a given wavelength.
get_value()	Get the amplitude mask as a numpy/cupy array
phi_at_lambda(wavelengthInNm[, slicey, slicex])	Calculate the phase of the electric field at a given wavelength.
product(ef2[, subrect])	Multiply the electric field by another electric field.
reset()	Reset to zero phase and unitary amplitude
resize(dimx, dimy[, pitch])	Resize the electric field
restore_from_passata(filename[, ...])	Restore a Pupilstop object from a PASSATA format file.
set_value(v)	Set a new amplitude mask.
square_modulus(wavelengthInNm)	Compute the square modulus (intensity) of the electric field at a given wavelength.
sub_ef([xfrom, xto, yfrom, yto, idx])	Extract a subregion of the electric field.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

checkOther
from_header
get_fits_header
init_logging
masked_area
monitorMem
printMemUsage
restore
save
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

static from_header(hdr, target_device_idx=None)

get_fits_header()

get_value()

Get the amplitude mask as a numpy/cupy array

static restore(filename, target_device_idx=None)

static restore_from_passata(filename, target_device_idx=None)

Restore a Pupilstop object from a PASSATA format file.

save(filename, overwrite=True)

set_value(v)

Set a new amplitude mask. Arrays are not reallocated

Recmat

class specula.data_objects.recmat.Recmat(recmat, modes2recLayer=None, norm_factor: float = 0, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Reconstruction matrix data object. This class holds the information about the reconstruction matrix, which maps slopes to modes. The reconstruction matrix axes are [modes, slopes].

Attributes:

nmodes

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the recmat as a numpy/cupy array
set_value(v)	Set new values for the recmat Arrays are not reallocated
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
init_logging
monitorMem
printMemUsage
reduce_size
restore
save
seconds_to_t
set_modes2recLayer
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a Recmat object.

Attributes:

nmodes

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()	Get the recmat as a numpy/cupy array
set_value(v)	Set new values for the recmat Arrays are not reallocated
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
init_logging
monitorMem
printMemUsage
reduce_size
restore
save
seconds_to_t
set_modes2recLayer
startMemUsageCount
stopMemUsageCount
t_to_seconds

static from_header(filename, target_device_idx=None)

get_fits_header()

get_value()

Get the recmat as a numpy/cupy array

property nmodes

reduce_size(nModesToBeDiscarded)

static restore(filename, target_device_idx=None)

save(filename, overwrite=False)

set_modes2recLayer(modes2recLayer)

set_value(v)

Set new values for the recmat Arrays are not reallocated

Simul Params

class specula.data_objects.simul_params.SimulParams(pixel_pupil: int = None, pixel_pitch: float = None, root_dir: str = '.', total_time: float = 0.1, time_step: float = 0.001, zenithAngleInDeg: float = 0, display_server: bool = False, stepping: bool = False, add_modules: List[str] = [])

Bases: BaseDataObj

Simulation Parameters data object. This class holds the parameters of the simulation, such as pixel size, time step, total time, zenith angle, etc.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

init_logging
monitorMem
printMemUsage
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Parameters:

• root_dir (str) – The root dir for the simulation

• pixel_pupil (int [pixel]) – The diameter in pixels of the simulation pupil

• pixel_pitch (float [m]) – The dimension in meters of a pixel (telescope diameter = pixel_pupil * pixel_pitch)

• total_time (float [s]) – The total time duration of the simulation

• time_step (float [s]) – The duration of a single timestep in seconds (number of timesteps = int(total_time/time_step) )

• zenithAngleInDeg (float [deg]) – The zenith angle of the telescope

• display_server (bool) – Activate web server for simulation display

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

init_logging
monitorMem
printMemUsage
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Slopes

class specula.data_objects.slopes.Slopes(length: int = None, slopes=None, interleave: bool = False, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Slopes data object. Holds a slopes vector, which can be interleaved (XYXYXY…) or not (XXX…YYY…). X and Y slopes can be accessed independently, and a 2d map is available.

Attributes:

size

Get the size of the slopes array.

xslopes

Get the x slopes as a numpy/cupy array.

yslopes

Get the y slopes as a numpy/cupy array.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get2d()	Get the slopes as a 2d map.
get_fits_header()	Get the FITS header for the Slopes object.
get_value()	Get the slopes as anumpy/cupy array
indx()	Get the indices for the x slopes.
indy()	Get the indices for the y slopes.
resize(new_size)	Resize the slopes array to a new size.
rotate(angle[, flipx, flipy])	Rotate the x and y slopes by a given angle, and optionally flip them along the x and/or y axes.
save(filename[, overwrite])	Save the Slopes object to a FITS file.
set_value(v)	Set new slopes values.
subtract(s2)	Subtract another slopes object.
sum(s2, factor)	Sum the slopes with another slopes object.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.
x_remap2d(frame, idx)	Remap the x slopes to a 2d frame.
y_remap2d(frame, idx)	Remap the y slopes to a 2d frame.

array_for_display
from_header
init_logging
monitorMem
printMemUsage
restore
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize the base data object.

Parameters: target_device_idx: int, optional

device to be targeted for data storage. Set to -1 for CPU, to 0 for the first GPU device, 1 for the second GPU device, etc.

precision: int, optional

if None will use the global_precision, otherwise set to 0 for double, 1 for single

Attributes:

size

Get the size of the slopes array.

xslopes

Get the x slopes as a numpy/cupy array.

yslopes

Get the y slopes as a numpy/cupy array.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get2d()	Get the slopes as a 2d map.
get_fits_header()	Get the FITS header for the Slopes object.
get_value()	Get the slopes as anumpy/cupy array
indx()	Get the indices for the x slopes.
indy()	Get the indices for the y slopes.
resize(new_size)	Resize the slopes array to a new size.
rotate(angle[, flipx, flipy])	Rotate the x and y slopes by a given angle, and optionally flip them along the x and/or y axes.
save(filename[, overwrite])	Save the Slopes object to a FITS file.
set_value(v)	Set new slopes values.
subtract(s2)	Subtract another slopes object.
sum(s2, factor)	Sum the slopes with another slopes object.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.
x_remap2d(frame, idx)	Remap the x slopes to a 2d frame.
y_remap2d(frame, idx)	Remap the y slopes to a 2d frame.

array_for_display
from_header
init_logging
monitorMem
printMemUsage
restore
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

array_for_display()

static from_header(hdr, target_device_idx=None)

get2d()

Get the slopes as a 2d map.

get_fits_header()

Get the FITS header for the Slopes object.

get_value()

Get the slopes as anumpy/cupy array

indx()

Get the indices for the x slopes.

indy()

Get the indices for the y slopes.

resize(new_size)

Resize the slopes array to a new size.

Parameters:

new_size (int) – The new size for the slopes array.

Notes

This method reallocates the slopes array to the specified new size and updates the indices for x and y slopes according to the interleave setting.

static restore(filename, target_device_idx=None)

rotate(angle, flipx=False, flipy=False)

Rotate the x and y slopes by a given angle, and optionally flip them along the x and/or y axes.

Parameters:

• angle (float) – The angle (in degrees) by which to rotate the slopes.

• flipx (bool, optional) – If True, flip the x slopes (default: False).

• flipy (bool, optional) – If True, flip the y slopes (default: False).

• place. (This operation modifies the xslopes and yslopes attributes in)

save(filename, overwrite=True)

Save the Slopes object to a FITS file.

Parameters:

• filename (str) – The path to the FITS file where the Slopes object will be saved.

• overwrite (bool, optional) – If True, overwrite the existing file if it exists (default: True).

• file. (The method writes the slopes data and relevant metadata to a FITS)

• header (The main HDU contains only the)

• stored (and the slopes data is)

• 'SLOPES'. (in an image extension named)

set_value(v)

Set new slopes values. Arrays are not reallocated

property size

Get the size of the slopes array.

subtract(s2)

Subtract another slopes object.

sum(s2, factor)

Sum the slopes with another slopes object.

x_remap2d(frame, idx)

Remap the x slopes to a 2d frame.

property xslopes

Get the x slopes as a numpy/cupy array.

y_remap2d(frame, idx)

Remap the y slopes to a 2d frame.

property yslopes

Get the y slopes as a numpy/cupy array.

Source

class specula.data_objects.source.Source(polar_coordinates: list, magnitude: float, wavelengthInNm: float, height: float = inf, band: str = '', zero_point: float = 0, error_coord: tuple = (0.0, 0.0), target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Source data object. Holds the properties of a source, such as polar coordinates, magnitude, wavelength, height, band, zero point, and error in coordinates.

Attributes:

phi

Get the angle of the source in radians.

phi_deg

Get the angle of the source in degrees.

polar_coordinates

r

Get the radius of the source in radians.

r_arcsec

Get the radius of the source in arcseconds.

x_coord

Get the x coordinate of the source in meters.

y_coord

Get the y coordinate of the source in meters.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()
phot_density()	Get the photometric density of the source.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a Source object.

Parameters:

• polar_coordinates (list [arcsec, deg]) – The polar coordinates [radius in arcsec, angle in deg] of the source.

• magnitude (float [1]) – The magnitude of the source.

• wavelengthInNm (float [nm]) – The wavelength of the source.

• height (float [m], optional) – The height of the source (default: infinity, i.e., astronomical source).

• band (str) – The photometric band of the source (default: ‘’).

• zero_point (float [1], optional) – The photometric zero point (default: 0).

• error_coord (tuple [arcsec, deg], optional) – Error to add to the polar coordinates [radius error in arcsec, angle error in deg] (default: (0., 0.)).

• target_device_idx (int [1], optional) – Device index for computation (default: None).

• precision (int [1], optional) – Precision for computation (default: None).

Attributes:

phi

Get the angle of the source in radians.

phi_deg

Get the angle of the source in degrees.

polar_coordinates

r

Get the radius of the source in radians.

r_arcsec

Get the radius of the source in arcseconds.

x_coord

Get the x coordinate of the source in meters.

y_coord

Get the y coordinate of the source in meters.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
get_value()
phot_density()	Get the photometric density of the source.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
init_logging
monitorMem
printMemUsage
restore
save
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

static from_header(hdr, target_device_idx=None)

get_fits_header()

get_value()

property phi

Get the angle of the source in radians.

property phi_deg

Get the angle of the source in degrees.

phot_density()

Get the photometric density of the source.

property polar_coordinates

property r

Get the radius of the source in radians.

property r_arcsec

Get the radius of the source in arcseconds.

static restore(filename, target_device_idx=None)

save(filename, overwrite=False)

set_value(v)

property x_coord

Get the x coordinate of the source in meters.

property y_coord

Get the y coordinate of the source in meters.

Spatio Temp Array

class specula.data_objects.spatio_temp_array.SpatioTempArray(array, time_vector, time_axis: int = -1, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Spatio-temporal array data object. This class holds a multi-dimensional spatio-temporal array with an associated time vector. Input arrays can have temporal evolution on the first or last axis. Internally, data are always stored in time-first layout: array[i, …] is associated with time_vector[i].

Methods

array_for_display()	Return the array data for display purposes.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
from_header(hdr[, target_device_idx, precision])	Create empty SpatioTempArray from FITS header metadata.
get_fits_header()	Get the FITS header for saving.
get_time_vector()	Get the time vector.
get_value()	Get array data in internal time-first layout: array[time, ...].
restore(filename[, target_device_idx])	Restore a SpatioTempArray object from a FITS file.
save(filename)	Save the SpatioTempArray data to a FITS file.
set_time_vector(val)	Set the time vector in-place.
set_value(val)	Set array data in-place accepting time-first or time-last layout.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

init_logging
monitorMem
printMemUsage
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a SpatioTempArray object.

Parameters:

• array (array-like [1]) – N-dimensional array with temporal evolution on first or last axis. Can be 1D (time only), 2D (spatial + time), 3D (spatial + spatial + time), etc. Typically in nm for phase screens.

• time_vector (array-like [s]) – 1D array of time values corresponding to the selected temporal axis of array. Must have length equal to array.shape[time_axis].

• time_axis (int [1], optional) – Temporal axis of input array. Supported values are 0 (time-first) and -1 (time-last). Internal storage is always time-first. Default is -1.

• target_device_idx (int [1], optional) – Device to be targeted for data storage. Set to -1 for CPU, to 0 for the first GPU device, 1 for the second GPU device, etc. Default is None (uses global setting).

• precision (int [1], optional) – Precision setting. If None will use the global_precision, otherwise set to 0 for double, 1 for single.

Methods

array_for_display()	Return the array data for display purposes.
copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
from_header(hdr[, target_device_idx, precision])	Create empty SpatioTempArray from FITS header metadata.
get_fits_header()	Get the FITS header for saving.
get_time_vector()	Get the time vector.
get_value()	Get array data in internal time-first layout: array[time, ...].
restore(filename[, target_device_idx])	Restore a SpatioTempArray object from a FITS file.
save(filename)	Save the SpatioTempArray data to a FITS file.
set_time_vector(val)	Set the time vector in-place.
set_value(val)	Set array data in-place accepting time-first or time-last layout.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

init_logging
monitorMem
printMemUsage
seconds_to_t
startMemUsageCount
stopMemUsageCount
t_to_seconds

array_for_display()

Return the array data for display purposes.

static from_header(hdr, target_device_idx=None, precision=None)

Create empty SpatioTempArray from FITS header metadata.

This creates an object with uninitialised arrays of the correct shape based on the header metadata (used for pre-allocation before loading data).

Parameters:

• hdr (astropy.io.fits.Header) – FITS header containing ARSHAPE and NTIME metadata.

• target_device_idx (int, optional) – Device to be targeted for data storage.

• precision (int, optional) – Precision setting.

Returns:

Object with uninitialised arrays of correct shape and time vector length.

Return type:

SpatioTempArray

get_fits_header()

Get the FITS header for saving.

Uses abbreviated keywords to comply with FITS standard (max 8 characters). Saves shape as space-separated string in ARSHAPE comment for readability. Internal temporal axis is stored in TAXIS (always 0).

get_time_vector()

Get the time vector.

get_value()

Get array data in internal time-first layout: array[time, …].

static restore(filename, target_device_idx=None)

Restore a SpatioTempArray object from a FITS file.

Parameters:

• filename (str) – Path to the FITS file created by save().

• target_device_idx (int, optional) – Device to be targeted for data storage.

Returns:

Restored object.

Return type:

SpatioTempArray

save(filename)

Save the SpatioTempArray data to a FITS file.

The array is stored in internal time-first layout as primary HDU and the time vector as an extension.

set_time_vector(val)

Set the time vector in-place.

set_value(val)

Set array data in-place accepting time-first or time-last layout.

Ssr Filter Data

class specula.data_objects.ssr_filter_data.SsrFilterData(A, B, C, D, n_modes=None, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

State Space Representation Filter Data data object. This class stores discrete-time state-space filter coefficients.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
from_gain(gain[, target_device_idx])	Create a simple proportional controller: y[k] = gain * u[k].
from_integrator(gain[, ff, target_device_idx])	Create a discrete integrator with optional forgetting factor.
get_eigenvalues()	Get eigenvalues of A matrix for stability analysis.
is_stable()	Check stability: all eigenvalues must be inside unit circle.
restore(filename[, target_device_idx])	Restore filter data from FITS file.
save(filename)	Save filter data to FITS file.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
get_value
init_logging
monitorMem
printMemUsage
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

SsrFilterData

Note

State Space Representation Filter Data.

This class stores discrete-time state-space filter coefficients in the format: 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 argument of SsrFilter class.

All filters are combined into single block-diagonal matrices: - A: block-diagonal state transition matrix (total_states x total_states) - B: input matrix mapping each input to its states (total_states x nfilter) - C: output matrix mapping states to outputs (nfilter x total_states) - D: diagonal feedthrough matrix (nfilter x nfilter) - x: concatenated state vector (total_states,) - u: input vector (nfilter,) - y: output vector (nfilter,)

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
from_gain(gain[, target_device_idx])	Create a simple proportional controller: y[k] = gain * u[k].
from_integrator(gain[, ff, target_device_idx])	Create a discrete integrator with optional forgetting factor.
get_eigenvalues()	Get eigenvalues of A matrix for stability analysis.
is_stable()	Check stability: all eigenvalues must be inside unit circle.
restore(filename[, target_device_idx])	Restore filter data from FITS file.
save(filename)	Save filter data to FITS file.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

from_header
get_fits_header
get_value
init_logging
monitorMem
printMemUsage
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

static from_gain(gain, target_device_idx=None)

Create a simple proportional controller: y[k] = gain * u[k].

Parameters:

gain (array_like) – Gains for each filter

Returns:

Pure gain (no state): y = gain * u

Return type:

SsrFilterData

static from_header(hdr)

static from_integrator(gain, ff=None, target_device_idx=None)

Create a discrete integrator with optional forgetting factor.

Parameters:

• gain (array_like) – Integrator gains

• ff (array_like, optional) – Forgetting factors (leaky integrator). If None, uses 1.0 (pure integrator).

Returns:

State-space representation: x[k+1] = ff*x[k] + gain*u[k] y[k] = x[k+1]

Return type:

SsrFilterData

get_eigenvalues()

Get eigenvalues of A matrix for stability analysis.

get_fits_header()

get_value()

is_stable()

Check stability: all eigenvalues must be inside unit circle.

static restore(filename, target_device_idx=None)

Restore filter data from FITS file.

save(filename)

Save filter data to FITS file.

set_value(v)

Subap Data

class specula.data_objects.subap_data.SubapData(idxs, display_map, nx: int, ny: int, energy_th: float = 0, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Subaperture data object. This class holds the information about the subapertures, i.e. the indices of the pixels belonging to each subaperture of a Shack-Hartmann sensor.

Attributes:

n_subaps

np_sub

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
display_map_idx(n)	Returns the position of subaperture n.
restore(filename[, target_device_idx])	Restores the SubapData from a file.
save(filename[, overwrite])	Saves the SubapData to a file.
subap_idx(n)	Returns the indices of subaperture n.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

init_logging
monitorMem
printMemUsage
seconds_to_t
single_mask
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a SubapData object.

Parameters:

• idxs ([1]) – np.array[n_subaps, n_pixels] of pixel indices in a flattened pixel array for each subaperture

• display_map ([1]) – np.array[n_subaps] of subaperture indices on a flattened nx * ny array, used for display only

• nx (int [1]) – number of subapertures in the X (horizontal) direction

• ny (int [1]) – number of subapertures in the Y (vertical) direction

• energy_th (float [1]) – energy threshold for subaperture validity (default: 0)

• target_device_idx (int [1]) – device index for computation (default: None)

• precision (int [1]) – precision for computation (default: None)

Attributes:

n_subaps

np_sub

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
display_map_idx(n)	Returns the position of subaperture n.
restore(filename[, target_device_idx])	Restores the SubapData from a file.
save(filename[, overwrite])	Saves the SubapData to a file.
subap_idx(n)	Returns the indices of subaperture n.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

init_logging
monitorMem
printMemUsage
seconds_to_t
single_mask
startMemUsageCount
stopMemUsageCount
t_to_seconds

display_map_idx(n)

Returns the position of subaperture n.

property n_subaps

property np_sub

static restore(filename, target_device_idx=None)

Restores the SubapData from a file.

save(filename, overwrite=False)

Saves the SubapData to a file.

single_mask()

subap_idx(n)

Returns the indices of subaperture n.

Time History

class specula.data_objects.time_history.TimeHistory(time_history, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Time history data object. This class holds the time history of a variable, such as the seeing value, during the simulation. The time history is stored as a 1D array,

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
restore(filename[, target_device_idx])	Restores the TimeHistory data from a file.
save(filename)	Saves the TimeHistory data to a file.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

array_for_display
from_header
get_fits_header
get_value
init_logging
monitorMem
printMemUsage
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

Initialize a TimeHistory object.

Methods

copyTo(target_device_idx)	Duplicate a data object on another device, alllocating all CPU/GPU arrays on the new device.
restore(filename[, target_device_idx])	Restores the TimeHistory data from a file.
save(filename)	Saves the TimeHistory data to a file.
to_xp(v[, dtype, force_copy])	Method wrapping the global to_xp function.
transferDataTo(destobj[, force_reallocation])	Copy CPU/GPU arrays into an existing data object: iterate over all self attributes and, if a CPU or GPU array is detected, copy data into destobj without reallocating.

array_for_display
from_header
get_fits_header
get_value
init_logging
monitorMem
printMemUsage
seconds_to_t
set_value
startMemUsageCount
stopMemUsageCount
t_to_seconds

array_for_display()

static from_header(hdr, target_device_idx=None)

get_fits_header()

get_value()

static restore(filename, target_device_idx=None)

Restores the TimeHistory data from a file.

save(filename)

Saves the TimeHistory data to a file.

set_value(val)