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/latest/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, 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.

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.

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 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

Phasescreen

class specula.data_objects.phasescreen.Phasescreen(dimx: int, dimy: int, L0: float, seed: int, target_device_idx: int = None, precision: int = None)

Bases: BaseDataObj

Phasescreen 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 phasescreen as a numpy/cupy array
`set_value`(v)	Set a new phasescreen.
`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 Phasescreen 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 phasescreen as a numpy/cupy array
`set_value`(v)	Set a new phasescreen.
`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 phasescreen as a numpy/cupy array

static restore(filename, target_device_idx=None)

save(filename, overwrite=True)

set_value(v): Set a new phasescreen. 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_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_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_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
stepping (bool) – Activate interactive single-stepping mode
add_modules (list of str) – Optional additional modules to add to the search path when importing processing objects

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)