Q&A
This page collects design questions that clarify how the inventory model should be used.
Use an OpticalComponent for something the light passes through in optical-distance order. Use a container for physical housing, protection, or assembly context.
For example, a fiber interval belongs in the ordered optical path:
optical_components:
- type: FiberSegment
name: Sensing fiber interval
optical_length: 300.0
container: sensing_cableThe cable, pipe, conduit, or splice box that contains or houses the component is modeled separately:
resources:
sensing_cable:
type: Cable
name: Solifos BRUsens DAS AC3
splice_box_01:
type: Enclosure
name: Splice box 01
enclosure_type: splice_boxThis keeps the optical path sequence focused on optical propagation while preserving physical asset metadata.
They are independent interval tracks over optical distance.
OpticalComponent describes what the light passes through. Geometry describes where the optical path is. CouplingCondition describes acoustic or mechanical coupling. Their boundaries often differ.
optical_components:
- type: FiberSegment
name: Sensing cable
optical_length: 720.0
geometries:
- name: East trench
optical_length: 300.0
- name: North trench
optical_length: 120.0
- name: Surface run
optical_length: 300.0
coupling_conditions:
- coupling_type: trench
attachment: direct_burial
optical_length: 420.0
- coupling_type: surface
attachment: loose
optical_length: 300.0The only requirement is that each track is internally ordered and meaningful over the optical path distance axis.
Use an interval with optical_length and leave the unknown descriptive fields unset.
geometries:
- name: Unknown lead-in geometry
optical_length: 50.0
coupling_conditions:
- optical_length: 50.0This is better than pretending the metadata is known. The unknown interval still preserves the optical-distance budget, so later geometry or coupling updates can replace it without shifting the rest of the path.
Treat breaks and repairs as changes in time-valid optical paths.
Close the old OpticalPath with an end_time, then add a new path with a start_time. Keep both under the same FiberArray when they represent the same observing identity.
fiber_arrays:
- code: SIMP
optical_paths:
- name: Original path
start_time: "2026-06-01"
end_time: "2026-06-12T10:30:00"
- name: Repaired path
start_time: "2026-06-12T10:30:00"This preserves history and lets patches resolve the path that was valid at their acquisition time.
FiberArray owns the durable observing identity: network-style code, optical paths, and the fact that this is a named fiber array.
Acquisition owns data-stream configuration: location code, acquisition code, data type, units, interrogator, sample rate, gauge length, spatial interval, and start distance.
fiber_arrays:
- code: SIMP
name: Simple trench array
acquisitions:
- code: RAW
location_code: ""
data_category: DAS
data_type: strain
sample_rate: 250.0
gauge_length: 2.0If the same physical fiber array is recorded with multiple gauge lengths or processed products, use multiple acquisitions under the same fiber array.
All coordinate-bearing inventory objects are interpreted using the inventory-level CoordinateReferenceSystem.
The CRS defines coordinate_labels, such as:
coordinate_reference_system:
authority: EPSG
code: 4979
name: WGS 84 3D
coordinate_labels: [longitude, latitude, elevation]
units: [degree, degree, meter]Point-like objects such as Station and Channel can use a generic coordinates tuple ordered by those labels:
stations:
- code: VA01
coordinates: [2.103905, 48.807461, 115.0]They can also use dynamic fields matching coordinate_labels. For a geographic CRS, latitude, longitude, and elevation are still valid:
stations:
- code: VA01
longitude: 2.103905
latitude: 48.807461
elevation: 115.0Fiber geometry uses the same CRS, but stores coordinate sequences along optical distance:
geometries:
- optical_length: 300.0
distance: [50.0, 350.0]
coordinates:
- [2.103905, 48.807461, 115.0]
- [2.108000, 48.807461, 115.0]Use limited nested containers. The light still passes through a FiberSegment, the fiber segment is in a Cable, and the cable can be inside an Enclosure with enclosure_type: pipe or enclosure_type: conduit.
resources:
pipe_01:
type: Enclosure
name: North access pipe
enclosure_type: pipe
material: steel
inner_diameter: 0.10
sensing_cable:
type: Cable
name: Solifos BRUsens DAS AC3
container: pipe_01The optical path remains focused on what light passes through:
optical_components:
- type: FiberSegment
name: Fiber inside sensing cable
optical_length: 1200.0
container: sensing_cableCoupling stays interval-specific:
coupling_conditions:
- optical_length: 1200.0
coupling_type: conduit
attachment: loose
medium: steelThis separates physical containment from acoustic or mechanical coupling.
Represent coils, slack loops, and compact clumps as ordinary optical path length with compact physical geometry.
The light still passes through a FiberSegment, so the coil belongs in the ordered optical components. The geometry can be point-like even when the optical interval is long: use repeated or nearly identical coordinates for the start and end of the interval.
optical_components:
- type: FiberSegment
name: Vault 2 slack coil
optical_length: 100.0
container: sensing_cable
notes: Coiled slack fiber in vault.
geometries:
- name: Vault 2 coil location
optical_length: 100.0
distance: [0.0, 100.0]
coordinates:
- [500.0, 120.0, 0.0]
- [500.0, 120.0, 0.0]Add coupling or annotation metadata so downstream consumers know this is intentional compact geometry, not missing survey detail:
coupling_conditions:
- optical_length: 100.0
coupling_type: coiled
attachment: loose
annotations:
- distance: 1200.0
optical_length: 100.0
label: slack coil
notes: Stored coil, not intended as sensing fiber.This avoids adding a special coil class while preserving the optical-distance budget and the physical interpretation.