Data Objects

Data objects in SPECULA serve as intelligent containers that connect processing objects and carry temporal information about when data was generated. They extend the BaseDataObj class and provide the essential data flow between computational components.

Core Concepts

Temporal Awareness: Every data object tracks its generation_time, allowing the simulation to maintain temporal consistency and detect when data needs to be refreshed.
Device Management: Data objects automatically handle GPU/CPU transfers through the copyTo() and transferDataTo() methods, enabling seamless computation across different devices.
Persistent Storage: All data objects implement save() and read() methods using FITS format, ensuring simulation data can be stored and reloaded.
Connection Framework: Data objects flow through the simulation graph as outputs from one processing object become inputs to another, creating a directed acyclic graph of computation.

Available Data Objects

Optical Wavefronts

ElectricField - Complex amplitude and phase information
Intensity - Detected intensity maps
Pixels - Digitized detector readouts

Wavefront Sensing

Slopes - Wavefront sensor measurements (x,y slopes)
SubapData - Subaperture geometry and validity maps

System Geometry

PupData - Telescope pupil geometry and indexing
Pupilstop - Pupil masks and obstruction patterns
Layer - Atmospheric or optical layers
Source - Guide star and science target definitions

Calibration Data

Intmat - Interaction matrices (slopes→commands)
Recmat - Reconstruction matrices (commands→slopes)
IFunc - Deformable mirror influence functions
M2C - Mode-to-command transformation matrices

Signal Processing

ConvolutionKernel - Generic convolution kernels
GaussianConvolutionKernel - Gaussian PSF kernels
IirFilterData - Digital filter coefficients
TimeHistory - Temporal data sequences

Specialized Components

LaserLaunchTelescope - Laser guide star launcher geometry
Lenslet - Shack-Hartmann lenslet arrays
InfinitePhaseScreen - Atmospheric turbulence screens

Persistence and Data Flow

SPECULA data objects implement specialized methods for seamless integration with the data storage and replay system:

Storage and Replay Integration

Data objects work automatically with DataStore and DataSource through standardized methods:

get_value() - Extracts the core numerical data for storage
from_header() - Reconstructs objects from stored headers
set_value() - Restores numerical data from storage

Supported Data Formats:

FITS: Default format, preserves metadata and ensures portability
Pickle: Python-specific format for complex objects

Usage Example

Data objects automatically manage temporal consistency:

class MyProcessor(BaseProcessingObj):
    def trigger_code(self):
        # Check if input data is current
        if self.local_inputs['wavefront'].generation_time != self.current_time:
            return  # Skip processing with stale data

        # Process current data
        input_wf = self.local_inputs['wavefront']
        result = self.process(input_wf.phase)

        # Update output with current timestamp
        self.outputs['processed'].value = result
        self.outputs['processed'].generation_time = self.current_time

Device Transfer Example

Moving data between GPU and CPU:

# Original data on GPU
gpu_slopes = Slopes(target_device_idx=0)  # GPU device 0

# Transfer to CPU for analysis
cpu_slopes = gpu_slopes.copyTo(target_device_idx=-1)  # CPU

# Data is automatically converted between CuPy and NumPy arrays

Persistence Example

Saving and loading calibration data:

# Save interaction matrix
intmat = Intmat(matrix_data, pupdata_tag='telescope_pupil')
intmat.save('calibration/interaction_matrix.fits')

# Load in another simulation
loaded_intmat = Intmat.restore('calibration/interaction_matrix.fits')

Key Design Principles:

Temporal Consistency: Every data object knows when it was created
Device Agnostic: Automatic GPU/CPU memory management
Persistent: All data can be saved and restored with full metadata
Type Safety: Each data type has specific validation and methods
Modular: Data objects can be combined and reused across simulations
Automatic Storage and Replay: Seamless integration with DataStore/DataSource pipeliner analysis

Data objects form the connective tissue of SPECULA simulations, ensuring that information flows correctly through the processing pipeline while maintaining temporal and spatial consistency. The integrated storage system enables complete reproducibility of simulation results and facilitates post-processing analysis workflows.