Base Classes

SPECULA uses several base classes that provide the foundation for all processing objects and data structures. These classes are designed to be inherited and should not be instantiated directly.

Overview

The base classes in SPECULA provide:

Common interfaces for all processing objects
Standardized data handling patterns
Connection management between simulation components
Time synchronization mechanisms
Device management (CPU/GPU) capabilities

Core Base Classes

BaseProcessingObj

The foundation for all processing objects in SPECULA. Provides:

Input/output connection management
Setup and trigger mechanisms
Stream processing support
Device allocation (CPU/GPU)

BaseValue

Base class for all data containers. Handles:

Data storage and access
Type validation
Memory management
Device-specific operations

BaseDataObj

Extended data objects with additional metadata:

Generation time tracking
Data provenance
Serialization support

BaseTimeObj

Time-aware objects for simulation synchronization:

High-resolution timestamp management (nanosecond precision)
Time conversion utilities (seconds ↔ internal format)
Device allocation and memory monitoring
Mathematical library integration (scipy/cupyx)

TemplateProcessingObj

Template and example for creating new processing objects:

Standard structure patterns
Input/output setup examples
Best practice demonstrations

Connection System

The connection system (specula.connections) provides:

InputValue: Typed connections between objects
Connection validation: Ensures type compatibility
Data flow management: Handles data transfer between components
Lazy evaluation: Data is computed only when needed

Usage Guidelines

When creating new SPECULA components:

Always inherit from the appropriate base class
Don’t instantiate base classes directly
Override required methods (setup(), trigger_code(), etc.)
Use the connection system for inter-object communication
Follow naming conventions established by base classes

Example Structure

from specula.base_processing_obj import BaseProcessingObj
from specula.connections import InputValue

class MyProcessor(BaseProcessingObj):
    def __init__(self, ...):
        super().__init__(...)

        # Define inputs and outputs
        self.result = BaseValue(value = self.xp.zeros(100),
                                target_device_idx=target_device_idx,
                                precision=precision)
        self.inputs['data_in'] = InputValue(type=MyDataType)
        self.outputs['result'] = self.result

    def setup(self):
        # Initialize processing
        super().setup()
        pass

    def trigger_code(self):
        # Main processing logic
        input_data = self.inputs['data_in'].get()
        self.result.value[:] = self.process(input_data)

    def post_trigger(self):
        super().post_trigger()
        self.result.generation_time = self.current_time

For detailed API documentation of all base classes, see Base Classes API.