Observation Model ================= .. verified:: 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 ^^^^^^^^^^^^^^^^^^ .. mermaid:: 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 ^^^^^^^^^^^^^^^^ :py:class:`~ccat_ops_db.models.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 :py:class:`~ccat_ops_db.models.ObservingProgram`. SubObservingProgram ^^^^^^^^^^^^^^^^^^^ :py:class:`~ccat_ops_db.models.SubObservingProgram` breaks a program into smaller scientific sub-projects. Not all :py:class:`~ccat_ops_db.models.ObsUnit` objects need to belong to a :py:class:`~ccat_ops_db.models.SubObservingProgram`. For complete attribute details, see :py:class:`~ccat_ops_db.models.SubObservingProgram`. Source ^^^^^^ :py:class:`~ccat_ops_db.models.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 :py:class:`~ccat_ops_db.models.Source`, :py:class:`~ccat_ops_db.models.FixedSource`, :py:class:`~ccat_ops_db.models.SolarSystemObject`, and :py:class:`~ccat_ops_db.models.ConstantElevationSource`. ObsUnit ^^^^^^^ :py:class:`~ccat_ops_db.models.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 :py:class:`~ccat_ops_db.models.ExecutedObsUnit` records. For complete attribute details, see :py:class:`~ccat_ops_db.models.ObsUnit`. ObsMode ^^^^^^^ :py:class:`~ccat_ops_db.models.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 :py:class:`~ccat_ops_db.models.ObsMode`. ObservationConfiguration ^^^^^^^^^^^^^^^^^^^^^^^^^ :py:class:`~ccat_ops_db.models.ObservationConfiguration` provides detailed parameters for how to execute the observation. It is polymorphic with subclasses for different instrument types: :py:class:`~ccat_ops_db.models.ChaiObservationConfiguration` for CHAI observations and :py:class:`~ccat_ops_db.models.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 :py:class:`~ccat_ops_db.models.ChaiTiling` and :py:class:`~ccat_ops_db.models.ChaiInparParameter` which are linked to the :py:class:`~ccat_ops_db.models.ChaiObservationConfiguration` Table. For complete attribute details, see :py:class:`~ccat_ops_db.models.ObservationConfiguration`, :py:class:`~ccat_ops_db.models.ChaiObservationConfiguration`, and :py:class:`~ccat_ops_db.models.PrimeCamObservationConfiguration`. PreScheduledSlot ^^^^^^^^^^^^^^^^ :py:class:`~ccat_ops_db.models.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 :py:class:`~ccat_ops_db.models.PreScheduledSlot`. Execution Layer --------------- ExecutedObsUnit ^^^^^^^^^^^^^^^ :py:class:`~ccat_ops_db.models.ExecutedObsUnit` records an actual execution of an :py:class:`~ccat_ops_db.models.ObsUnit`. One :py:class:`~ccat_ops_db.models.ObsUnit` can have many :py:class:`~ccat_ops_db.models.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 :doc:`/ops-db-api/docs/deep-dive/transaction-buffering`). For complete attribute details, see :py:class:`~ccat_ops_db.models.ExecutedObsUnit`. Execution Flow -------------- .. mermaid:: 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 .. **Version and History Tracking** .. The ``version`` and ``history`` fields on :py:class:`~ccat_ops_db.models.ObsUnit` .. allow updates to observing parameters while preserving provenance. **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. Related Documentation --------------------- * Complete API reference: :doc:`../api_reference/models` * Observatory hierarchy: :doc:`observatory_hierarchy` * Data model: :doc:`data_model` * Data transfer workflows: :doc:`/data-transfer/docs/index`