Refactor: instruments have sensors by j-atkins · Pull Request #328 · Parcels-code/virtualship

j-atkins · 2026-04-10T11:44:26Z

Overview

This PR centralises/abstracts instrument sensor/variable sampling logic so that each instrument declares which sensors it carries (e.g. TEMPERATURE, SALINITY, VELOCITY). Users can configure which sensors are active for each instrument in the expedition YAML.

This helps pave the way for easy addition of BGC sensors to the Argo float in a future PR (#234), and consolidation of CTD + CTD_BGC into a single instrument (#260) with a combined sensor allowlist. Also makes it straightforward to add new sensors to any instrument in the future (e.g., #312, #313), and streamlines them process for developers to add new instruments (i.e. #237)

Major changes

sensors.py in instruments/ defines the SensorType class and per-instrument allowlists (so that there is control over which sensors each instrument supports and users cannot configure unsupported sensors).
New SensorConfig pydantic model and sensors field in every instrument config in expedition.py.
New SensorRegistry in utils.py that maps each SensorType to its FieldSet key, Copernicus variable name, category (phys/bgc), and Parcels particle variable name(s).
- Per-instrument parcticle classes are now built dynamically at runtime based on which sensors are active, but the fixed/mechanical variables are still hard-coded in the instrument files, e.g. cycle_phase for Argo Floats.

API change

As mentioned above, the instruments config section of the expedition YAML now has a sensors list field, where users specify which sensors are active. For example, below the CTD is configured to sample TEMPERATURE and SALINITY:

ctd_config:
stationkeeping_time_minutes: 50min_depth_meter: -11max_depth_meter: -2000sensors:
- TEMPERATURE
- SALINITY

If the sensors list is omitted, it default to all valid sensors for that instrument.
By using allowlists for each instrument, it will not allow non-sensical sensor combinations (e.g. BGC sensors on an ADCP).
Will also not allow an empty sensor list, at least one sensor must be active.

Additional change

Argo Float sampling kernels have been separated from the vertical-movement kernel, making it easier to add BGC sensors in a future PR.

Follow-up PRs

The plan CLI tool will need updating to account for sensor configuration options. Currently not broken but doesn't give option to configure sensors. (New issue to be opened)
Docs update to clearly communicate which sensors each instrument accepts, and how to configure them in either the plan tool or the expedition YAML. (New issue to be opened)
Merge CTD + CTD_BGC into a single instrument. (Unify CTD and CTD_BGC to one instrument #260)
Add BGC sampling to Argo Floats (New ARGO_BGC instrument #234)

Tests

Update existing tests and add new tests to cover new sensor logic

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

… kernels from the argo vertical movement kernel to enable easier scalability

…operty shorthands

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

…pping from class attributes

… etc. across different instrument configs

for more information, see https://pre-commit.ci

…ampling kernels

…p into refactor-sensors

for more information, see https://pre-commit.ci

… methods to sensors.py

…le_vars from list to tuple for sensor definitions

…p into refactor-sensors

for more information, see https://pre-commit.ci

…p into refactor-sensors

for more information, see https://pre-commit.ci

j-atkins · 2026-04-30T08:58:12Z

I have addressed various comments from the first round of review on this PR. See below for a list of main changes:

Renamed all _*_FIXED_VARIABLES lists to _*_NONSENSOR_VARIABLES
Renamed _SensorMeta to _Sensor, added type_: SensorType as a field so each sensor object is self-describing, and moved the class + SENSOR_REGISTRY from utils.py into sensors.py
New _InstrumentConfigMixin in expedition.py defines shared methods that can be flexibly inherited across the InstrumentConfig models, addresses duplication flagged.
- Note, though, also that this logic has been extended to other preexisting datetime related parts of the InstrumetConfigs, e.g. minutes and lifetime params (so this is some 'bonus' refactoring).
- The tests associated with each method are maintained and a new test added to test_expedition.py to check that all InstrumentConfig models inherit from the mixin.
Instrument subclasses (e.g. CTDInstrument) must now define sensor_kernel dictionary to map the sensor types to the relevant sampling kernels as a class attribute. This is checked by the Instrument base class and also a test added to test_base.py. Means the allowlists for different sensor types are now explicitly defined and managed within each instrument class, which is nice for further centralising instrument characteristics and behaviours.

j-atkins · 2026-04-10T11:44:26Z

Overview

This PR centralises/abstracts instrument sensor/variable sampling logic so that each instrument declares which sensors it carries (e.g. TEMPERATURE, SALINITY, VELOCITY). Users can configure which sensors are active for each instrument in the expedition YAML.

This helps pave the way for easy addition of BGC sensors to the Argo float in a future PR (#234), and consolidation of CTD + CTD_BGC into a single instrument (#260) with a combined sensor allowlist. Also makes it straightforward to add new sensors to any instrument in the future (e.g., #312, #313), and streamlines them process for developers to add new instruments (i.e. #237)

Major changes

sensors.py in instruments/ defines the SensorType class and per-instrument allowlists (so that there is control over which sensors each instrument supports and users cannot configure unsupported sensors).
New SensorConfig pydantic model and sensors field in every instrument config in expedition.py.
New SensorRegistry in utils.py that maps each SensorType to its FieldSet key, Copernicus variable name, category (phys/bgc), and Parcels particle variable name(s).
- Per-instrument parcticle classes are now built dynamically at runtime based on which sensors are active, but the fixed/mechanical variables are still hard-coded in the instrument files, e.g. cycle_phase for Argo Floats.

API change

As mentioned above, the instruments config section of the expedition YAML now has a sensors list field, where users specify which sensors are active. For example, below the CTD is configured to sample TEMPERATURE and SALINITY:

ctd_config:
stationkeeping_time_minutes: 50min_depth_meter: -11max_depth_meter: -2000sensors:
- TEMPERATURE
- SALINITY

If the sensors list is omitted, it default to all valid sensors for that instrument.
By using allowlists for each instrument, it will not allow non-sensical sensor combinations (e.g. BGC sensors on an ADCP).
Will also not allow an empty sensor list, at least one sensor must be active.

Additional change

Argo Float sampling kernels have been separated from the vertical-movement kernel, making it easier to add BGC sensors in a future PR.

Follow-up PRs

The plan CLI tool will need updating to account for sensor configuration options. Currently not broken but doesn't give option to configure sensors. (New issue to be opened)
Docs update to clearly communicate which sensors each instrument accepts, and how to configure them in either the plan tool or the expedition YAML. (New issue to be opened)
Merge CTD + CTD_BGC into a single instrument. (Unify CTD and CTD_BGC to one instrument #260)
Add BGC sampling to Argo Floats (New ARGO_BGC instrument #234)

Tests

Update existing tests and add new tests to cover new sensor logic

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

… kernels from the argo vertical movement kernel to enable easier scalability

…operty shorthands

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

…pping from class attributes

… etc. across different instrument configs

for more information, see https://pre-commit.ci

…ampling kernels

…p into refactor-sensors

for more information, see https://pre-commit.ci

… methods to sensors.py

…le_vars from list to tuple for sensor definitions

…p into refactor-sensors

for more information, see https://pre-commit.ci

…p into refactor-sensors

for more information, see https://pre-commit.ci

j-atkins · 2026-04-30T08:58:12Z

I have addressed various comments from the first round of review on this PR. See below for a list of main changes:

Renamed all _*_FIXED_VARIABLES lists to _*_NONSENSOR_VARIABLES
Renamed _SensorMeta to _Sensor, added type_: SensorType as a field so each sensor object is self-describing, and moved the class + SENSOR_REGISTRY from utils.py into sensors.py
New _InstrumentConfigMixin in expedition.py defines shared methods that can be flexibly inherited across the InstrumentConfig models, addresses duplication flagged.
- Note, though, also that this logic has been extended to other preexisting datetime related parts of the InstrumetConfigs, e.g. minutes and lifetime params (so this is some 'bonus' refactoring).
- The tests associated with each method are maintained and a new test added to test_expedition.py to check that all InstrumentConfig models inherit from the mixin.
Instrument subclasses (e.g. CTDInstrument) must now define sensor_kernel dictionary to map the sensor types to the relevant sampling kernels as a class attribute. This is checked by the Instrument base class and also a test added to test_base.py. Means the allowlists for different sensor types are now explicitly defined and managed within each instrument class, which is nice for further centralising instrument characteristics and behaviours.

j-atkins · 2026-04-10T11:44:26Z

Overview

This PR centralises/abstracts instrument sensor/variable sampling logic so that each instrument declares which sensors it carries (e.g. TEMPERATURE, SALINITY, VELOCITY). Users can configure which sensors are active for each instrument in the expedition YAML.

This helps pave the way for easy addition of BGC sensors to the Argo float in a future PR (#234), and consolidation of CTD + CTD_BGC into a single instrument (#260) with a combined sensor allowlist. Also makes it straightforward to add new sensors to any instrument in the future (e.g., #312, #313), and streamlines them process for developers to add new instruments (i.e. #237)

Major changes

sensors.py in instruments/ defines the SensorType class and per-instrument allowlists (so that there is control over which sensors each instrument supports and users cannot configure unsupported sensors).
New SensorConfig pydantic model and sensors field in every instrument config in expedition.py.
New SensorRegistry in utils.py that maps each SensorType to its FieldSet key, Copernicus variable name, category (phys/bgc), and Parcels particle variable name(s).
- Per-instrument parcticle classes are now built dynamically at runtime based on which sensors are active, but the fixed/mechanical variables are still hard-coded in the instrument files, e.g. cycle_phase for Argo Floats.

API change

As mentioned above, the instruments config section of the expedition YAML now has a sensors list field, where users specify which sensors are active. For example, below the CTD is configured to sample TEMPERATURE and SALINITY:

ctd_config:
stationkeeping_time_minutes: 50min_depth_meter: -11max_depth_meter: -2000sensors:
- TEMPERATURE
- SALINITY

If the sensors list is omitted, it default to all valid sensors for that instrument.
By using allowlists for each instrument, it will not allow non-sensical sensor combinations (e.g. BGC sensors on an ADCP).
Will also not allow an empty sensor list, at least one sensor must be active.

Additional change

Argo Float sampling kernels have been separated from the vertical-movement kernel, making it easier to add BGC sensors in a future PR.

Follow-up PRs

The plan CLI tool will need updating to account for sensor configuration options. Currently not broken but doesn't give option to configure sensors. (New issue to be opened)
Docs update to clearly communicate which sensors each instrument accepts, and how to configure them in either the plan tool or the expedition YAML. (New issue to be opened)
Merge CTD + CTD_BGC into a single instrument. (Unify CTD and CTD_BGC to one instrument #260)
Add BGC sampling to Argo Floats (New ARGO_BGC instrument #234)

Tests

Update existing tests and add new tests to cover new sensor logic

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

… kernels from the argo vertical movement kernel to enable easier scalability

…operty shorthands

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

…pping from class attributes

… etc. across different instrument configs

for more information, see https://pre-commit.ci

…ampling kernels

…p into refactor-sensors

for more information, see https://pre-commit.ci

… methods to sensors.py

…le_vars from list to tuple for sensor definitions

…p into refactor-sensors

for more information, see https://pre-commit.ci

…p into refactor-sensors

for more information, see https://pre-commit.ci

j-atkins · 2026-04-30T08:58:12Z

I have addressed various comments from the first round of review on this PR. See below for a list of main changes:

Renamed all _*_FIXED_VARIABLES lists to _*_NONSENSOR_VARIABLES
Renamed _SensorMeta to _Sensor, added type_: SensorType as a field so each sensor object is self-describing, and moved the class + SENSOR_REGISTRY from utils.py into sensors.py
New _InstrumentConfigMixin in expedition.py defines shared methods that can be flexibly inherited across the InstrumentConfig models, addresses duplication flagged.
- Note, though, also that this logic has been extended to other preexisting datetime related parts of the InstrumetConfigs, e.g. minutes and lifetime params (so this is some 'bonus' refactoring).
- The tests associated with each method are maintained and a new test added to test_expedition.py to check that all InstrumentConfig models inherit from the mixin.
Instrument subclasses (e.g. CTDInstrument) must now define sensor_kernel dictionary to map the sensor types to the relevant sampling kernels as a class attribute. This is checked by the Instrument base class and also a test added to test_base.py. Means the allowlists for different sensor types are now explicitly defined and managed within each instrument class, which is nice for further centralising instrument characteristics and behaviours.

j-atkins · 2026-04-10T11:44:26Z

Overview

This PR centralises/abstracts instrument sensor/variable sampling logic so that each instrument declares which sensors it carries (e.g. TEMPERATURE, SALINITY, VELOCITY). Users can configure which sensors are active for each instrument in the expedition YAML.

This helps pave the way for easy addition of BGC sensors to the Argo float in a future PR (#234), and consolidation of CTD + CTD_BGC into a single instrument (#260) with a combined sensor allowlist. Also makes it straightforward to add new sensors to any instrument in the future (e.g., #312, #313), and streamlines them process for developers to add new instruments (i.e. #237)

Major changes

sensors.py in instruments/ defines the SensorType class and per-instrument allowlists (so that there is control over which sensors each instrument supports and users cannot configure unsupported sensors).
New SensorConfig pydantic model and sensors field in every instrument config in expedition.py.
New SensorRegistry in utils.py that maps each SensorType to its FieldSet key, Copernicus variable name, category (phys/bgc), and Parcels particle variable name(s).
- Per-instrument parcticle classes are now built dynamically at runtime based on which sensors are active, but the fixed/mechanical variables are still hard-coded in the instrument files, e.g. cycle_phase for Argo Floats.

API change

As mentioned above, the instruments config section of the expedition YAML now has a sensors list field, where users specify which sensors are active. For example, below the CTD is configured to sample TEMPERATURE and SALINITY:

ctd_config:
stationkeeping_time_minutes: 50min_depth_meter: -11max_depth_meter: -2000sensors:
- TEMPERATURE
- SALINITY

If the sensors list is omitted, it default to all valid sensors for that instrument.
By using allowlists for each instrument, it will not allow non-sensical sensor combinations (e.g. BGC sensors on an ADCP).
Will also not allow an empty sensor list, at least one sensor must be active.

Additional change

Argo Float sampling kernels have been separated from the vertical-movement kernel, making it easier to add BGC sensors in a future PR.

Follow-up PRs

The plan CLI tool will need updating to account for sensor configuration options. Currently not broken but doesn't give option to configure sensors. (New issue to be opened)
Docs update to clearly communicate which sensors each instrument accepts, and how to configure them in either the plan tool or the expedition YAML. (New issue to be opened)
Merge CTD + CTD_BGC into a single instrument. (Unify CTD and CTD_BGC to one instrument #260)
Add BGC sampling to Argo Floats (New ARGO_BGC instrument #234)

Tests

Update existing tests and add new tests to cover new sensor logic

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

… kernels from the argo vertical movement kernel to enable easier scalability

…operty shorthands

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

…pping from class attributes

… etc. across different instrument configs

for more information, see https://pre-commit.ci

…ampling kernels

…p into refactor-sensors

for more information, see https://pre-commit.ci

… methods to sensors.py

…le_vars from list to tuple for sensor definitions

…p into refactor-sensors

for more information, see https://pre-commit.ci

…p into refactor-sensors

for more information, see https://pre-commit.ci

j-atkins · 2026-04-30T08:58:12Z

I have addressed various comments from the first round of review on this PR. See below for a list of main changes:

Renamed all _*_FIXED_VARIABLES lists to _*_NONSENSOR_VARIABLES
Renamed _SensorMeta to _Sensor, added type_: SensorType as a field so each sensor object is self-describing, and moved the class + SENSOR_REGISTRY from utils.py into sensors.py
New _InstrumentConfigMixin in expedition.py defines shared methods that can be flexibly inherited across the InstrumentConfig models, addresses duplication flagged.
- Note, though, also that this logic has been extended to other preexisting datetime related parts of the InstrumetConfigs, e.g. minutes and lifetime params (so this is some 'bonus' refactoring).
- The tests associated with each method are maintained and a new test added to test_expedition.py to check that all InstrumentConfig models inherit from the mixin.
Instrument subclasses (e.g. CTDInstrument) must now define sensor_kernel dictionary to map the sensor types to the relevant sampling kernels as a class attribute. This is checked by the Instrument base class and also a test added to test_base.py. Means the allowlists for different sensor types are now explicitly defined and managed within each instrument class, which is nice for further centralising instrument characteristics and behaviours.

j-atkins · 2026-04-10T11:44:26Z

Overview

This PR centralises/abstracts instrument sensor/variable sampling logic so that each instrument declares which sensors it carries (e.g. TEMPERATURE, SALINITY, VELOCITY). Users can configure which sensors are active for each instrument in the expedition YAML.

This helps pave the way for easy addition of BGC sensors to the Argo float in a future PR (#234), and consolidation of CTD + CTD_BGC into a single instrument (#260) with a combined sensor allowlist. Also makes it straightforward to add new sensors to any instrument in the future (e.g., #312, #313), and streamlines them process for developers to add new instruments (i.e. #237)

Major changes

sensors.py in instruments/ defines the SensorType class and per-instrument allowlists (so that there is control over which sensors each instrument supports and users cannot configure unsupported sensors).
New SensorConfig pydantic model and sensors field in every instrument config in expedition.py.
New SensorRegistry in utils.py that maps each SensorType to its FieldSet key, Copernicus variable name, category (phys/bgc), and Parcels particle variable name(s).
- Per-instrument parcticle classes are now built dynamically at runtime based on which sensors are active, but the fixed/mechanical variables are still hard-coded in the instrument files, e.g. cycle_phase for Argo Floats.

API change

As mentioned above, the instruments config section of the expedition YAML now has a sensors list field, where users specify which sensors are active. For example, below the CTD is configured to sample TEMPERATURE and SALINITY:

ctd_config:
stationkeeping_time_minutes: 50min_depth_meter: -11max_depth_meter: -2000sensors:
- TEMPERATURE
- SALINITY

If the sensors list is omitted, it default to all valid sensors for that instrument.
By using allowlists for each instrument, it will not allow non-sensical sensor combinations (e.g. BGC sensors on an ADCP).
Will also not allow an empty sensor list, at least one sensor must be active.

Additional change

Argo Float sampling kernels have been separated from the vertical-movement kernel, making it easier to add BGC sensors in a future PR.

Follow-up PRs

The plan CLI tool will need updating to account for sensor configuration options. Currently not broken but doesn't give option to configure sensors. (New issue to be opened)
Docs update to clearly communicate which sensors each instrument accepts, and how to configure them in either the plan tool or the expedition YAML. (New issue to be opened)
Merge CTD + CTD_BGC into a single instrument. (Unify CTD and CTD_BGC to one instrument #260)
Add BGC sampling to Argo Floats (New ARGO_BGC instrument #234)

Tests

Update existing tests and add new tests to cover new sensor logic

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

… kernels from the argo vertical movement kernel to enable easier scalability

…operty shorthands

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

…pping from class attributes

… etc. across different instrument configs

for more information, see https://pre-commit.ci

…ampling kernels

…p into refactor-sensors

for more information, see https://pre-commit.ci

… methods to sensors.py

…le_vars from list to tuple for sensor definitions

…p into refactor-sensors

for more information, see https://pre-commit.ci

…p into refactor-sensors

for more information, see https://pre-commit.ci

j-atkins · 2026-04-30T08:58:12Z

I have addressed various comments from the first round of review on this PR. See below for a list of main changes:

Renamed all _*_FIXED_VARIABLES lists to _*_NONSENSOR_VARIABLES
Renamed _SensorMeta to _Sensor, added type_: SensorType as a field so each sensor object is self-describing, and moved the class + SENSOR_REGISTRY from utils.py into sensors.py
New _InstrumentConfigMixin in expedition.py defines shared methods that can be flexibly inherited across the InstrumentConfig models, addresses duplication flagged.
- Note, though, also that this logic has been extended to other preexisting datetime related parts of the InstrumetConfigs, e.g. minutes and lifetime params (so this is some 'bonus' refactoring).
- The tests associated with each method are maintained and a new test added to test_expedition.py to check that all InstrumentConfig models inherit from the mixin.
Instrument subclasses (e.g. CTDInstrument) must now define sensor_kernel dictionary to map the sensor types to the relevant sampling kernels as a class attribute. This is checked by the Instrument base class and also a test added to test_base.py. Means the allowlists for different sensor types are now explicitly defined and managed within each instrument class, which is nice for further centralising instrument characteristics and behaviours.

j-atkins · 2026-04-10T11:44:26Z

Overview

This PR centralises/abstracts instrument sensor/variable sampling logic so that each instrument declares which sensors it carries (e.g. TEMPERATURE, SALINITY, VELOCITY). Users can configure which sensors are active for each instrument in the expedition YAML.

This helps pave the way for easy addition of BGC sensors to the Argo float in a future PR (#234), and consolidation of CTD + CTD_BGC into a single instrument (#260) with a combined sensor allowlist. Also makes it straightforward to add new sensors to any instrument in the future (e.g., #312, #313), and streamlines them process for developers to add new instruments (i.e. #237)

Major changes

sensors.py in instruments/ defines the SensorType class and per-instrument allowlists (so that there is control over which sensors each instrument supports and users cannot configure unsupported sensors).
New SensorConfig pydantic model and sensors field in every instrument config in expedition.py.
New SensorRegistry in utils.py that maps each SensorType to its FieldSet key, Copernicus variable name, category (phys/bgc), and Parcels particle variable name(s).
- Per-instrument parcticle classes are now built dynamically at runtime based on which sensors are active, but the fixed/mechanical variables are still hard-coded in the instrument files, e.g. cycle_phase for Argo Floats.

API change

As mentioned above, the instruments config section of the expedition YAML now has a sensors list field, where users specify which sensors are active. For example, below the CTD is configured to sample TEMPERATURE and SALINITY:

ctd_config:
stationkeeping_time_minutes: 50min_depth_meter: -11max_depth_meter: -2000sensors:
- TEMPERATURE
- SALINITY

If the sensors list is omitted, it default to all valid sensors for that instrument.
By using allowlists for each instrument, it will not allow non-sensical sensor combinations (e.g. BGC sensors on an ADCP).
Will also not allow an empty sensor list, at least one sensor must be active.

Additional change

Argo Float sampling kernels have been separated from the vertical-movement kernel, making it easier to add BGC sensors in a future PR.

Follow-up PRs

The plan CLI tool will need updating to account for sensor configuration options. Currently not broken but doesn't give option to configure sensors. (New issue to be opened)
Docs update to clearly communicate which sensors each instrument accepts, and how to configure them in either the plan tool or the expedition YAML. (New issue to be opened)
Merge CTD + CTD_BGC into a single instrument. (Unify CTD and CTD_BGC to one instrument #260)
Add BGC sampling to Argo Floats (New ARGO_BGC instrument #234)

Tests

Update existing tests and add new tests to cover new sensor logic

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

… kernels from the argo vertical movement kernel to enable easier scalability

…operty shorthands

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

…pping from class attributes

… etc. across different instrument configs

for more information, see https://pre-commit.ci

…ampling kernels

…p into refactor-sensors

for more information, see https://pre-commit.ci

… methods to sensors.py

…le_vars from list to tuple for sensor definitions

…p into refactor-sensors

for more information, see https://pre-commit.ci

…p into refactor-sensors

for more information, see https://pre-commit.ci

j-atkins · 2026-04-30T08:58:12Z

I have addressed various comments from the first round of review on this PR. See below for a list of main changes:

Renamed all _*_FIXED_VARIABLES lists to _*_NONSENSOR_VARIABLES
Renamed _SensorMeta to _Sensor, added type_: SensorType as a field so each sensor object is self-describing, and moved the class + SENSOR_REGISTRY from utils.py into sensors.py
New _InstrumentConfigMixin in expedition.py defines shared methods that can be flexibly inherited across the InstrumentConfig models, addresses duplication flagged.
- Note, though, also that this logic has been extended to other preexisting datetime related parts of the InstrumetConfigs, e.g. minutes and lifetime params (so this is some 'bonus' refactoring).
- The tests associated with each method are maintained and a new test added to test_expedition.py to check that all InstrumentConfig models inherit from the mixin.
Instrument subclasses (e.g. CTDInstrument) must now define sensor_kernel dictionary to map the sensor types to the relevant sampling kernels as a class attribute. This is checked by the Instrument base class and also a test added to test_base.py. Means the allowlists for different sensor types are now explicitly defined and managed within each instrument class, which is nice for further centralising instrument characteristics and behaviours.

j-atkins · 2026-04-10T11:44:26Z

Overview

This PR centralises/abstracts instrument sensor/variable sampling logic so that each instrument declares which sensors it carries (e.g. TEMPERATURE, SALINITY, VELOCITY). Users can configure which sensors are active for each instrument in the expedition YAML.

This helps pave the way for easy addition of BGC sensors to the Argo float in a future PR (#234), and consolidation of CTD + CTD_BGC into a single instrument (#260) with a combined sensor allowlist. Also makes it straightforward to add new sensors to any instrument in the future (e.g., #312, #313), and streamlines them process for developers to add new instruments (i.e. #237)

Major changes

sensors.py in instruments/ defines the SensorType class and per-instrument allowlists (so that there is control over which sensors each instrument supports and users cannot configure unsupported sensors).
New SensorConfig pydantic model and sensors field in every instrument config in expedition.py.
New SensorRegistry in utils.py that maps each SensorType to its FieldSet key, Copernicus variable name, category (phys/bgc), and Parcels particle variable name(s).
- Per-instrument parcticle classes are now built dynamically at runtime based on which sensors are active, but the fixed/mechanical variables are still hard-coded in the instrument files, e.g. cycle_phase for Argo Floats.

API change

As mentioned above, the instruments config section of the expedition YAML now has a sensors list field, where users specify which sensors are active. For example, below the CTD is configured to sample TEMPERATURE and SALINITY:

ctd_config:
stationkeeping_time_minutes: 50min_depth_meter: -11max_depth_meter: -2000sensors:
- TEMPERATURE
- SALINITY

If the sensors list is omitted, it default to all valid sensors for that instrument.
By using allowlists for each instrument, it will not allow non-sensical sensor combinations (e.g. BGC sensors on an ADCP).
Will also not allow an empty sensor list, at least one sensor must be active.

Additional change

Argo Float sampling kernels have been separated from the vertical-movement kernel, making it easier to add BGC sensors in a future PR.

Follow-up PRs

The plan CLI tool will need updating to account for sensor configuration options. Currently not broken but doesn't give option to configure sensors. (New issue to be opened)
Docs update to clearly communicate which sensors each instrument accepts, and how to configure them in either the plan tool or the expedition YAML. (New issue to be opened)
Merge CTD + CTD_BGC into a single instrument. (Unify CTD and CTD_BGC to one instrument #260)
Add BGC sampling to Argo Floats (New ARGO_BGC instrument #234)

Tests

Update existing tests and add new tests to cover new sensor logic

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

… kernels from the argo vertical movement kernel to enable easier scalability

…operty shorthands

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

…pping from class attributes

… etc. across different instrument configs

for more information, see https://pre-commit.ci

…ampling kernels

…p into refactor-sensors

for more information, see https://pre-commit.ci

… methods to sensors.py

…le_vars from list to tuple for sensor definitions

…p into refactor-sensors

for more information, see https://pre-commit.ci

…p into refactor-sensors

for more information, see https://pre-commit.ci

j-atkins · 2026-04-30T08:58:12Z

I have addressed various comments from the first round of review on this PR. See below for a list of main changes:

Renamed all _*_FIXED_VARIABLES lists to _*_NONSENSOR_VARIABLES
Renamed _SensorMeta to _Sensor, added type_: SensorType as a field so each sensor object is self-describing, and moved the class + SENSOR_REGISTRY from utils.py into sensors.py
New _InstrumentConfigMixin in expedition.py defines shared methods that can be flexibly inherited across the InstrumentConfig models, addresses duplication flagged.
- Note, though, also that this logic has been extended to other preexisting datetime related parts of the InstrumetConfigs, e.g. minutes and lifetime params (so this is some 'bonus' refactoring).
- The tests associated with each method are maintained and a new test added to test_expedition.py to check that all InstrumentConfig models inherit from the mixin.
Instrument subclasses (e.g. CTDInstrument) must now define sensor_kernel dictionary to map the sensor types to the relevant sampling kernels as a class attribute. This is checked by the Instrument base class and also a test added to test_base.py. Means the allowlists for different sensor types are now explicitly defined and managed within each instrument class, which is nice for further centralising instrument characteristics and behaviours.

j-atkins · 2026-04-10T11:44:26Z

Overview

This PR centralises/abstracts instrument sensor/variable sampling logic so that each instrument declares which sensors it carries (e.g. TEMPERATURE, SALINITY, VELOCITY). Users can configure which sensors are active for each instrument in the expedition YAML.

This helps pave the way for easy addition of BGC sensors to the Argo float in a future PR (#234), and consolidation of CTD + CTD_BGC into a single instrument (#260) with a combined sensor allowlist. Also makes it straightforward to add new sensors to any instrument in the future (e.g., #312, #313), and streamlines them process for developers to add new instruments (i.e. #237)

Major changes

sensors.py in instruments/ defines the SensorType class and per-instrument allowlists (so that there is control over which sensors each instrument supports and users cannot configure unsupported sensors).
New SensorConfig pydantic model and sensors field in every instrument config in expedition.py.
New SensorRegistry in utils.py that maps each SensorType to its FieldSet key, Copernicus variable name, category (phys/bgc), and Parcels particle variable name(s).
- Per-instrument parcticle classes are now built dynamically at runtime based on which sensors are active, but the fixed/mechanical variables are still hard-coded in the instrument files, e.g. cycle_phase for Argo Floats.

API change

As mentioned above, the instruments config section of the expedition YAML now has a sensors list field, where users specify which sensors are active. For example, below the CTD is configured to sample TEMPERATURE and SALINITY:

ctd_config:
stationkeeping_time_minutes: 50min_depth_meter: -11max_depth_meter: -2000sensors:
- TEMPERATURE
- SALINITY

If the sensors list is omitted, it default to all valid sensors for that instrument.
By using allowlists for each instrument, it will not allow non-sensical sensor combinations (e.g. BGC sensors on an ADCP).
Will also not allow an empty sensor list, at least one sensor must be active.

Additional change

Argo Float sampling kernels have been separated from the vertical-movement kernel, making it easier to add BGC sensors in a future PR.

Follow-up PRs

The plan CLI tool will need updating to account for sensor configuration options. Currently not broken but doesn't give option to configure sensors. (New issue to be opened)
Docs update to clearly communicate which sensors each instrument accepts, and how to configure them in either the plan tool or the expedition YAML. (New issue to be opened)
Merge CTD + CTD_BGC into a single instrument. (Unify CTD and CTD_BGC to one instrument #260)
Add BGC sampling to Argo Floats (New ARGO_BGC instrument #234)

Tests

Update existing tests and add new tests to cover new sensor logic

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

… kernels from the argo vertical movement kernel to enable easier scalability

…operty shorthands

…pe enum

…_bgc

…ensors for instruments

…ated validations for each instrument

…igher level for scalability

…pping from class attributes

… etc. across different instrument configs

for more information, see https://pre-commit.ci

…ampling kernels

…p into refactor-sensors

for more information, see https://pre-commit.ci

… methods to sensors.py

…le_vars from list to tuple for sensor definitions

…p into refactor-sensors

for more information, see https://pre-commit.ci

…p into refactor-sensors

for more information, see https://pre-commit.ci

j-atkins · 2026-04-30T08:58:12Z

I have addressed various comments from the first round of review on this PR. See below for a list of main changes:

Renamed all _*_FIXED_VARIABLES lists to _*_NONSENSOR_VARIABLES
Renamed _SensorMeta to _Sensor, added type_: SensorType as a field so each sensor object is self-describing, and moved the class + SENSOR_REGISTRY from utils.py into sensors.py
New _InstrumentConfigMixin in expedition.py defines shared methods that can be flexibly inherited across the InstrumentConfig models, addresses duplication flagged.
- Note, though, also that this logic has been extended to other preexisting datetime related parts of the InstrumetConfigs, e.g. minutes and lifetime params (so this is some 'bonus' refactoring).
- The tests associated with each method are maintained and a new test added to test_expedition.py to check that all InstrumentConfig models inherit from the mixin.
Instrument subclasses (e.g. CTDInstrument) must now define sensor_kernel dictionary to map the sensor types to the relevant sampling kernels as a class attribute. This is checked by the Instrument base class and also a test added to test_base.py. Means the allowlists for different sensor types are now explicitly defined and managed within each instrument class, which is nice for further centralising instrument characteristics and behaviours.

j-atkins added 30 commits March 25, 2026 13:53

remove CTD_BGC instrument type from InstrumentType enum, add SensorTy…
ba585c2
…pe enum

update utils: add sensor def mapping and remove old references to ctd…
1f7e9b8
…_bgc

refactor: update SensorType enum and add source-truth for supported s…
dbaa319
…ensors for instruments

add sensors configuration for various instruments
a2a7c81

new registries and helper functions
67a04d8

update expedition models, now including SensorConfig model and associ…
057d9f9
…ated validations for each instrument

modify adcp instrument class, also abstract expansion to u and v to h…
b82118d
…igher level for scalability

dynamic particle class building takes JIT or Scipy particle
8d96d8f

raise error when instrument has zero sensors enabled
818e8f8

use centralised particle class builder for ADCP now as well
07c8461

batch update instrument subclasses adapted to refactored sensor logic
1bf517e

rename list
961f1fe

adapt argo subclass to sensor refactoring, also separate the sampling…
ee002d7
… kernels from the argo vertical movement kernel to enable easier scalability

consistent particle variable naming
4777217

add back in ctd_bgc for now
c419399

fix import
daabfc4

move sensor information to new sensors.py file
cece7bb

update imports across codebase
b429331

add validator/serialiser for reading from YAML, remove unnecessary pr…
882a419
…operty shorthands

re-add JITParticle to particle class when creating instruments
126ecc2

remove CTD_BGC instrument type from InstrumentType enum, add SensorTy…
9011b2d
…pe enum

update utils: add sensor def mapping and remove old references to ctd…
464b3e9
…_bgc

refactor: update SensorType enum and add source-truth for supported s…
2f7d82d
…ensors for instruments

add sensors configuration for various instruments
1d7c158

new registries and helper functions
f01bf0e

update expedition models, now including SensorConfig model and associ…
d9f9d10
…ated validations for each instrument

modify adcp instrument class, also abstract expansion to u and v to h…
c50c43f
…igher level for scalability

dynamic particle class building takes JIT or Scipy particle
bb91f0c

raise error when instrument has zero sensors enabled
b584d70

use centralised particle class builder for ADCP now as well
6fb6284

j-atkinsand others added 9 commits April 28, 2026 13:14

refactor sensor support handling across instruments to use dynamic ma…
9a00820
…pping from class attributes

refactor to mixin class for sharing serialisation, validation methods…
c97c248
… etc. across different instrument configs

fix tests for new notation
9cc09d2

[pre-commit.ci] auto fixes from pre-commit.com hooks
c5d3b18
for more information, see https://pre-commit.ci

change order of supported sensors in CTD_BGC sensors description
f24a6f1

neaten up instrument classes mapping sensor types to their relevant s…
9e40b6c
…ampling kernels

sensor_kernels as base class attribute
27a9b4e

Merge branch 'refactor-sensors' of github.com:OceanParcels/virtualshi…
08c2ef5
…p into refactor-sensors

[pre-commit.ci] auto fixes from pre-commit.com hooks
b057c4c
for more information, see https://pre-commit.ci

j-atkins mentioned this pull request Apr 29, 2026
Sampling kernels in sensor class #332
Open

j-atkinsand others added 10 commits April 29, 2026 10:29

rename sensor class, give type_ attribute and move sensor classes and…
399d5f4
… methods to sensors.py

move towards explit lists of parcels.Variable's in sensor class
5581c79

make particle_vars explicitly define parcels.Variables, change partic…
a29d860
…le_vars from list to tuple for sensor definitions

fix wrong type checking
c210815

tidy up type annotation
f6b0551

Merge branch 'refactor-sensors' of github.com:OceanParcels/virtualshi…
3b846e2
…p into refactor-sensors

[pre-commit.ci] auto fixes from pre-commit.com hooks
e9e15db
for more information, see https://pre-commit.ci

test for mixin
072f83b

Merge branch 'refactor-sensors' of github.com:OceanParcels/virtualshi…
decbd5d
…p into refactor-sensors

[pre-commit.ci] auto fixes from pre-commit.com hooks
3685048
for more information, see https://pre-commit.ci

j-atkins requested review from VeckoTheGecko and erikvansebille April 30, 2026 08:57

erikvansebille approved these changes Apr 30, 2026
View reviewed changes

j-atkins merged commit 47f4ab8 into mainMay 1, 2026
11 checks passed

j-atkins deleted the refactor-sensors branch May 1, 2026 13:24

This was referenced May 4, 2026
Unify CTD and CTD_BGC to one instrument #333
Merged
Update docs with sensor configuration instructions #334
Closed
Update virtualship plan to configure instrument sensors #335
Closed

j-atkins mentioned this pull request May 28, 2026
Refactoring: moving instrument/sensor validation into VirtualShip internals #346
Open