create the new set of instrument definitions ("next-v1")

# Versioned detector definitions used by Chip and the readout simulation steps

instrument_data:

  release: legacy-v1

  release: next-v1

  release_directory: null

  detector_overrides: {}

  # - pointing_file: null

  pointing_file: "/home/yuedong/Work/CSST_sim/input_data/pointing50_C9/pointing_50_1_n.dat"

  obs_config_file: "/home/yuedong/Work/csst_test/csst_msc_sim/config/obs_config_SCI.yaml"

  obs_config_file: "/home/yuedong/Work/Projects/csst_msc_sim/config/obs_config_SCI.yaml"

  # Run specific pointing(s):

  # - give a list of indexes of pointings: [ip_1, ip_2...]

  # path to PSF data

  # NOTE: only valid for "Interp" PSF

  # PSF models for photometry survey simulation

  psf_pho_dir: "/home/yuedong/Work/CSST_sim/input_data/PSFCube/set1_dynamic/"

  # psf_pho_dir: "/home/yuedong/Work/CSST_sim/input_data/PSFCube/set1_dynamic/"

  psf_pho_dir: "/home/yuedong/Work/CSST_sim/input_data/psfCube202607/"

  # PSF models for slitless spectrum survey simulation

  psf_sls_dir: "/home/yuedong/Work/CSST_sim/input_data/PSFCube/SLS_PSF_PCA_fp/"

# Define list of chips

# run_chips: [6,7,8,9,11,12,13,14,15,16,17,18,19,20,22,23,24,25] # Photometric chips

#run_chips: [1,2,3,4,5,10,21,26,27,28,29,30] # Spectroscopic chips

run_chips: [17]

run_chips: [7]

# Define observation sequence

call_sequence:

| Release compositions | `releases/<release>.yaml` | A small lock manifest that pins one definition set and one exact version of every reference category |

Every definition-set directory uses the fixed filenames `detector_types.yaml`,

`readout_modes.yaml`, `calibration_profiles.yaml`, `focal_plane.yaml`, and

`reference_assignments.yaml`; no additional definition-set manifest is required.

`readout_modes.yaml`, `calibration_profiles.yaml`, `focal_plane.yaml`,

`filters.yaml`, and `reference_assignments.yaml`; no additional definition-set

manifest is required.

A release can therefore combine, for example, cosmic-ray references `1.0.0`

with filter transmissions `2.1.0`. Pins are always exact; values such as `2.x`

- `legacy-v1`: definition set `legacy/1.0.0`;

- `next-v1`: definition set `next/1.0.0` with 31 science slots (`00` through

  `30`) and the existing FGS definitions;

- reference set `1.0.0` for each category in both compositions.

- `legacy-v1` pins reference set `1.0.0` for each category;

- `next-v1` pins detector responses, filter transmissions, and system

  throughputs `2.0.0`, while unchanged reference categories remain pinned to

  `1.0.0`.

Released versions should be treated as immutable. Publish changed definitions

or reference files under a new version, then add or update a composition

| Catalog | Owns |

|---|---|

| `detector_types.yaml` | Detector families and concrete detector types, including QE filenames, size, pitch, technology, and nominal electronics |

| `detector_types.yaml` | Detector families and concrete detector types, including default QE filenames, size, pitch, technology, and nominal electronics |

| `readout_modes.yaml` | Channel boxes, transforms, per-channel scan regions, raw placement, and output order |

| `calibration_profiles.yaml` | Electronics, defects, exposure recipes, and calibration reference IDs |

| `focal_plane.yaml` | Installed detector IDs, type/mode/calibration assignments, placement, filter, and survey role |

| `reference_assignments.yaml` | Semantic roles that map global, detector, filter, and slitless inputs to versioned reference files |

| `focal_plane.yaml` | Instrument shutter timing, installed detector IDs, type/mode/calibration assignments, optional per-detector QE filename, placement, canonical filter, response profile, and survey role |

| `filters.yaml` | Canonical filter names, explicit compatibility IDs, and photometric/spectroscopic/guiding roles |

| `reference_assignments.yaml` | Semantic roles that map global, detector, canonical-filter, response-profile, and slitless inputs to versioned reference files; canonical bands are keyed under `filter_references` |

Each reference-set directory directly contains its files. Definitions refer to

those files by name, while release compositions select the category versions.

Repository loading validates schemas, cross-catalog relationships, pinned

versions, and files referenced by detector or calibration definitions.

Focal-plane `optical_role.filter` values are canonical scientific bands. An

optional `response_profile` selects a channel-specific system response while

sub-band boundaries remain owned by the canonical filter. Throughput resolution

uses the detector profile first, then the filter's default response profile,

then a legacy filter-level throughput. Every spectral reference target declares

its wavelength unit, while response profiles declare whether detector QE is

already included.

Mechanical shutter timing is instrument-wide and is configured at the top

level of `focal_plane.yaml`:

```yaml

shutter:

  open_duration_s: 1.3

  close_duration_s: 1.3

```

Calibration profiles can override detector-wide electronics while retaining

per-channel patches for amplifier-specific measurements. Resolution proceeds

from detector-type nominal values through readout-channel, detector-calibration,

and channel-calibration overrides:

```yaml

electronics:

  gain_e_per_adu: 1.4

  bias_adu: 2000.0

channel_electronics:

  CH01:

    gain_e_per_adu: 1.39

```

## Runtime API

```python

from .models import BBox, ChannelGeometry, DetectorType, Electronics, ReadoutMode

from .detector_response import load_detector_response

from .models import (

    BBox,

    ChannelGeometry,

    DetectorType,

    Electronics,

    FilterCatalog,

    FilterDefinition,

    ReadoutMode,

    ResponseProfileDefinition,

    ShutterTiming,

)

from .references import (

    DEFAULT_RELEASE,

    ReferenceGroup,

    "DEFAULT_RELEASE",

    "DetectorType",

    "Electronics",

    "FilterCatalog",

    "FilterDefinition",

    "InstrumentRepository",

    "ReadoutMode",

    "ReferenceGroup",

    "ResolvedChannel",

    "ResolvedDetector",

    "ResponseProfileDefinition",

    "ShutterTiming",

    "emit_schemas",

    "get_builtin_repository",

    "load_detector_response",

    "materialized_reference_path",

    "reference",

    "reference_path",

schema_version: "1.0"

filters:

  nuv: {display_name: NUV, survey: photometric, legacy_id: 0, wide_full_depth_exposures: 4, deep_full_depth_exposures: 16}

  u: {display_name: u, survey: photometric, legacy_id: 1, wide_full_depth_exposures: 2, deep_full_depth_exposures: 8}

  g: {display_name: g, survey: photometric, legacy_id: 2, wide_full_depth_exposures: 2, deep_full_depth_exposures: 8}

  r: {display_name: r, survey: photometric, legacy_id: 3, wide_full_depth_exposures: 2, deep_full_depth_exposures: 8}

  i: {display_name: i, survey: photometric, legacy_id: 4, wide_full_depth_exposures: 2, deep_full_depth_exposures: 8}

  z: {display_name: z, survey: photometric, legacy_id: 5, wide_full_depth_exposures: 2, deep_full_depth_exposures: 8}

  y: {display_name: y, survey: photometric, legacy_id: 6, wide_full_depth_exposures: 4, deep_full_depth_exposures: 16}

  gu: {display_name: GU, survey: spectroscopic, legacy_id: 7, wide_full_depth_exposures: 4, deep_full_depth_exposures: 16}

  gv: {display_name: GV, survey: spectroscopic, legacy_id: 8, wide_full_depth_exposures: 4, deep_full_depth_exposures: 16}

  gi: {display_name: GI, survey: spectroscopic, legacy_id: 9, wide_full_depth_exposures: 4, deep_full_depth_exposures: 16}

  fgs: {display_name: FGS, survey: guiding, legacy_id: 10, wide_full_depth_exposures: null, deep_full_depth_exposures: null}