Observation Model#

✓
Documentation Verified Last checked: 2025-11-25 Reviewer: Christof Buchbender

This section explains how scientific observations are planned and executed in ops-db. There is a key distinction between planning (what we want to observe) and execution (what we actually observed).

Planning Layer#

The planning layer defines what observations should be performed. These are relatively stable entities that can be updated over time.

Planning Hierarchy#

        graph TB
    PROG[ObservingProgram]
    SUB[SubObservingProgram]
    OU[ObsUnit]
    SRC[Source]
    OBSMODE[ObsMode]
    CONFIG[ObservationConfiguration]
    IMCONFIG[InstrumentModuleConfiguration]

    PROG -->|has many| SUB
    PROG -->|has many| OU
    SUB -->|has many| OU
    SRC -->|observed by| OU
    OBSMODE -->|defines strategy for| OU
    CONFIG -->|configures| OU
    IMCONFIG -->|used in| OU

    style PROG fill:#e1f5ff
    style SUB fill:#e1f5ff
    style OU fill:#e1f5ff
    style SRC fill:#ffe1f5
    style OBSMODE fill:#e1ffe1
    style CONFIG fill:#ffe1f5

ObservingProgram#

ObservingProgram groups observations under a scientific program. Typically corresponds to an approved proposal with allocated telescope time.

Examples: “Galactic Ecology”, “CMB”, but also e.g “Calibration” or “Commissioning”

For complete attribute details, see ObservingProgram.

SubObservingProgram#

SubObservingProgram breaks a program into smaller scientific sub-projects. Not all ObsUnit objects need to belong to a SubObservingProgram.

For complete attribute details, see SubObservingProgram.

Source#

Source represents the astronomical target to be observed. It is a polymorphic base class with three concrete types:

FixedSource - Objects with fixed celestial coordinates (stars, galaxies, nebulae).

Example: Orion-KL as a FixedSource

SolarSystemObject - Planets, asteroids, comets.

Example: Jupiter as a SolarSystemObject

ConstantElevationSource - Survey areas observed at constant elevation.

Example: Large-area survey regions

For complete attribute details, see Source, FixedSource, SolarSystemObject, and ConstantElevationSource.

ObsUnit#

ObsUnit defines a schedulable observation unit - the fundamental building block of observing. This is a “template” for observations - it can be executed multiple times, producing multiple ExecutedObsUnit records.

For complete attribute details, see ObsUnit.

ObsMode#

ObsMode defines the observing strategy.

Examples:

  • CHAI: “otf_totalpower_map” (on-the-fly mapping)

  • PrimeCam: “constant_elevation” (constant elevation, constant azimuth velocity scans)

For complete attribute details, see ObsMode.

ObservationConfiguration#

ObservationConfiguration provides detailed parameters for how to execute the observation. It is polymorphic with subclasses for different instrument types: ChaiObservationConfiguration for CHAI observations and PrimeCamObservationConfiguration for Prime-Cam observations. This can contain parameters that can be loaded by the observation execution system, e.g. for CHAI we use KOSMASoftware and we store the what traditionally was contained in the inpar and tiling files under the Tables ChaiTiling and ChaiInparParameter which are linked to the ChaiObservationConfiguration Table.

For complete attribute details, see ObservationConfiguration, ChaiObservationConfiguration, and PrimeCamObservationConfiguration.

PreScheduledSlot#

PreScheduledSlot defines fixed time windows for specific observation units. Used for observations that must happen at specific times (e.g., time-critical transients, coordinated observations).

For complete attribute details, see PreScheduledSlot.

Execution Layer#

ExecutedObsUnit#

ExecutedObsUnit records an actual execution of an ObsUnit. One ObsUnit can have many ExecutedObsUnit records (repeated observations). Uses UUID instead of integer ID because these are created by telescope systems that may not have database connectivity at creation time (see /ops-db-api/docs/deep-dive/transaction-buffering).

For complete attribute details, see ExecutedObsUnit.

Execution Flow#

        sequenceDiagram
    participant Planner
    participant Scheduler
    participant Telescope
    participant DataAcq

    Planner->>ObsUnit: Create ObsUnit with Source, ObsMode, Config
    Scheduler->>ObsUnit: Select based on priorities/constraints
    Scheduler->>Telescope: Schedule observation
    Telescope->>ExecutedObsUnit: Create ExecutedObsUnit record
    Telescope->>DataAcq: Execute observation
    DataAcq->>RawDataFile: Create RawDataFile records
    DataAcq->>ExecutedObsUnit: Link data to execution

The Planning → Execution Flow#

  1. ObservingProgram defines the science case

  2. ObsUnits are created with Sources, ObsModes, and ObservationConfigurations

  3. Scheduler selects ObsUnits based on priorities, constraints, and conditions

  4. Telescope executes → creates ExecutedObsUnit

  5. Data acquisition creates RawDataFiles linked to the ExecutedObsUnit

Why This Structure?#

Separation of Planning and Execution

Allows:

  • Repeating observations (observe the same target multiple times)

  • Tracking actual vs. planned (e.g., if an observation is interrupted)

  • Updating plans without affecting historical records

Polymorphic Source Model

Accommodates different target types (fixed stars vs. moving planets vs. survey areas) without requiring separate observation models.

Configuration Layer

The configuration layer (ObservationConfiguration, InstrumentModuleConfiguration) provides instrument-specific parameters while keeping the core ObsUnit model general.