fix: clarify difference between instance and definition references

This changes instance references to be required, while definition
references are optional. It also changes the instance reference from
process simulation to pipeline by removing the TARGET key.

Author: jsolaas

src/libecalc/presentation/yaml/domain/reference_service.py

@@ -25,7 +25,7 @@
     YamlVariableSpeedCompressorTrainMultipleStreamsAndPressures,
 )
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_pipeline import YamlProcessPipeline
-from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnit
+from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnitDefinition
 from libecalc.presentation.yaml.yaml_types.streams.yaml_inlet_stream import YamlInletStream
 
 
@@ -80,7 +80,7 @@ def get_tabulated_model(self, reference: str) -> YamlTabularModel: ...
     def get_process_pipeline(self, reference: str) -> YamlProcessPipeline: ...
 
     @abc.abstractmethod
-    def get_process_unit(self, reference: str) -> YamlProcessUnit: ...
+    def get_process_unit(self, reference: str) -> YamlProcessUnitDefinition: ...
 
     @abc.abstractmethod
     def get_stream(self, reference: str) -> YamlInletStream: ...

src/libecalc/presentation/yaml/mappers/process/build_sections.py

@@ -3,7 +3,7 @@
     MappedSection,
     ProcessPartitioner,
 )
-from libecalc.presentation.yaml.yaml_types.process.yaml_process_references import ProcessUnitReference
+from libecalc.presentation.yaml.yaml_types.process.yaml_process_references import InstanceReference
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_simulation import YamlProcessConstraint
 from libecalc.process.fluid_stream.fluid_service import FluidService
 from libecalc.process.process_pipeline.process_unit import ProcessUnit, ProcessUnitId
@@ -25,7 +25,7 @@ def __init__(self):
     def partition_and_validate(
         self,
         process_unit_map: dict[ProcessUnitId, ProcessUnit],
-        unit_name_to_id: dict[ProcessUnitReference, ProcessUnitId],
+        unit_name_to_id: dict[InstanceReference, ProcessUnitId],
         pipeline_constraints: list[YamlProcessConstraint],
     ) -> list[MappedSection]:
         sections = self._partitioner.partition(

src/libecalc/presentation/yaml/mappers/process/process_partitioner.py

@@ -1,6 +1,6 @@
 from libecalc.common.ddd import value_object
 from libecalc.common.errors.ecalc_validation_error import EcalcValidationException
-from libecalc.presentation.yaml.yaml_types.process.yaml_process_references import ProcessUnitReference
+from libecalc.presentation.yaml.yaml_types.process.yaml_process_references import InstanceReference
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_simulation import YamlProcessConstraint
 from libecalc.process.process_pipeline.process_unit import ProcessUnit, ProcessUnitId
 from libecalc.process.process_units.compressor import Compressor
@@ -27,7 +27,7 @@ class ProcessPartitioner:
     @staticmethod
     def partition(
         process_unit_map: dict[ProcessUnitId, ProcessUnit],
-        unit_name_to_id: dict[ProcessUnitReference, ProcessUnitId],
+        unit_name_to_id: dict[InstanceReference, ProcessUnitId],
         pipeline_constraints: list[YamlProcessConstraint],
     ) -> list[MappedSection]:
         process_units = list(process_unit_map.values())

src/libecalc/presentation/yaml/mappers/process_simulation_mapper.py

@@ -45,20 +45,20 @@
 from libecalc.presentation.yaml.yaml_types.models.yaml_fluid import YamlCompositionFluidModel, YamlPredefinedFluidModel
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_pipeline import YamlProcessPipeline
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_references import (
-    ProcessUnitReference,
+    InstanceReference,
 )
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_simulation import (
     YamlProcessSimulation,
 )
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import (
-    YamlCompressor,
+    YamlCompressorDefinition,
     YamlCompressorModelChart,
-    YamlLiquidRemover,
-    YamlMixer,
-    YamlPressureDropper,
-    YamlProcessUnit,
-    YamlSplitter,
-    YamlTemperatureSetter,
+    YamlLiquidRemoverDefinition,
+    YamlMixerDefinition,
+    YamlPressureDropperDefinition,
+    YamlProcessUnitDefinition,
+    YamlSplitterDefinition,
+    YamlTemperatureSetterDefinition,
 )
 from libecalc.presentation.yaml.yaml_types.streams.yaml_inlet_stream import YamlInletStream, YamlInletStreamRate
 from libecalc.presentation.yaml.yaml_types.yaml_data_or_file import YamlFile
@@ -132,7 +132,7 @@ def __init__(
         self._resources = resources
         self._ecalc_event_service = ecalc_event_service
 
-    def _resolve_train_reference(self, ref: str | YamlProcessPipeline) -> YamlProcessPipeline:
+    def _resolve_pipeline_reference(self, ref: str | YamlProcessPipeline) -> YamlProcessPipeline:
         if isinstance(ref, str):
             return self._reference_service.get_process_pipeline(reference=ref)
         else:
@@ -173,7 +173,7 @@ def _get_compressor_chart(self, yaml_compressor_model_chart: YamlCompressorModel
                 yaml_curves, units=yaml_chart.units, control_margin=control_margin_fraction
             )
 
-    def _get_compressor(self, yaml_compressor: YamlCompressor) -> Compressor:
+    def _get_compressor(self, yaml_compressor: YamlCompressorDefinition) -> Compressor:
         chart: ChartData = self._get_compressor_chart(yaml_compressor_model_chart=yaml_compressor.compressor_model)
         return Compressor(
             compressor_chart=chart,
@@ -247,7 +247,7 @@ def _map_fluid_model(self, yaml_fluid_model: YamlFluidModel) -> FluidModel:
     def _validate_and_map_pipeline_events(
         self,
         yaml_pipeline: YamlProcessPipeline,
-        unit_name_to_id: dict[ProcessUnitReference, ProcessUnitId],
+        unit_name_to_id: dict[InstanceReference, ProcessUnitId],
     ) -> list[PipelineEvent]:
         """Validate pipeline event references and map to domain objects."""
         events: list[PipelineEvent] = []
@@ -265,7 +265,7 @@ def _validate_and_map_pipeline_events(
                 ) from None
 
             match change_to_yaml_process_unit:
-                case YamlCompressor():
+                case YamlCompressorDefinition():
                     change_to_unit = self._get_compressor(change_to_yaml_process_unit)
                 case _:
                     raise EcalcValidationException(
@@ -307,10 +307,10 @@ def map_process_simulation(
         for yaml_compressor_train_item in yaml_process_simulation.targets:
             problem_configuration_handlers = []
             shaft = VariableSpeedShaft()
-            item = self._resolve_train_reference(yaml_compressor_train_item.target)
+            item = self._resolve_pipeline_reference(yaml_compressor_train_item)
             process_unit_map: dict[ProcessUnitId, ProcessUnit] = {}
             compressor_ids: list[ProcessUnitId] = []
-            unit_name_to_id: dict[ProcessUnitReference, ProcessUnitId] = {}
+            unit_name_to_id: dict[InstanceReference, ProcessUnitId] = {}
             problem_time_series_configurations: dict[
                 ProcessUnitId,
                 TimeSeriesTemperatureSetterConfiguration
@@ -319,33 +319,33 @@ def map_process_simulation(
                 | TimeSeriesSplitterConfiguration,
             ] = {}
 
-            for yaml_pipeline_item in item.items:
+            for yaml_pipeline_item in item.process_units:
                 yaml_process_unit = yaml_pipeline_item.target
                 process_unit_name = yaml_pipeline_item.name
                 if isinstance(yaml_process_unit, str):
                     yaml_process_unit = self._reference_service.get_process_unit(yaml_process_unit)
 
                 match yaml_process_unit:
-                    case YamlCompressor():
+                    case YamlCompressorDefinition():
                         unit = self._get_compressor(yaml_process_unit)
                         compressor_ids.append(unit.get_id())
 
-                    case YamlPressureDropper():
+                    case YamlPressureDropperDefinition():
                         unit = PressureDropper(fluid_service=self._fluid_service)
                         problem_time_series_configurations[unit.get_id()] = TimeSeriesPressureDropperConfiguration(
                             pressure_drop_in_bara=self._map_pressure(yaml_process_unit.pressure_drop)
                         )
 
-                    case YamlTemperatureSetter():
+                    case YamlTemperatureSetterDefinition():
                         unit = TemperatureSetter(fluid_service=self._fluid_service)
                         problem_time_series_configurations[unit.get_id()] = TimeSeriesTemperatureSetterConfiguration(
                             temperature_in_celsius=self._map_temperature(yaml_process_unit.temperature)
                         )
 
-                    case YamlLiquidRemover():
+                    case YamlLiquidRemoverDefinition():
                         unit = LiquidRemover(fluid_service=self._fluid_service)
 
-                    case YamlMixer():
+                    case YamlMixerDefinition():
                         yaml_stream = self._resolve_stream_reference(yaml_process_unit.sidestream)
                         yaml_fluid_model = self._resolve_fluid_model_reference(yaml_stream.fluid_model)
                         unit = Mixer(fluid_service=self._fluid_service)
@@ -358,7 +358,7 @@ def map_process_simulation(
                             )
                         )
 
-                    case YamlSplitter():
+                    case YamlSplitterDefinition():
                         unit = Splitter(fluid_service=self._fluid_service)
                         problem_time_series_configurations[unit.get_id()] = TimeSeriesSplitterConfiguration(
                             offtake_rate=self._map_rate(yaml_process_unit.offtake_rate),
@@ -367,7 +367,7 @@ def map_process_simulation(
                     case _:
                         # Unreachable for valid YAML (pydantic discriminator rejects unknown types).
                         # Guards against bypassed parsing or new union variants missing a case.
-                        allowed_types = [t.__name__ for t in get_args(get_args(YamlProcessUnit)[0])]
+                        allowed_types = [t.__name__ for t in get_args(get_args(YamlProcessUnitDefinition)[0])]
                         raise EcalcValidationException(
                             f"Process unit of type '{type(yaml_process_unit).__name__}' is not allowed "
                             f"in a process pipeline. Allowed types are: {', '.join(allowed_types)}."

src/libecalc/presentation/yaml/yaml_models/pyyaml_yaml_model.py

@@ -38,7 +38,7 @@
     YamlProcessSimulation,
     YamlPumpProcessSimulation,
 )
-from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnit
+from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnitDefinition
 from libecalc.presentation.yaml.yaml_types.streams.yaml_inlet_stream import YamlInletStream
 from libecalc.presentation.yaml.yaml_types.time_series.yaml_time_series import YamlTimeSeriesCollection
 from libecalc.presentation.yaml.yaml_types.yaml_default_datetime import YamlDefaultDatetime
@@ -451,13 +451,13 @@ def fluid_models(self) -> dict[str, YamlFluidModel]:
         return fluid_models
 
     @property
-    def process_units(self) -> dict[str, YamlProcessUnit]:
-        process_units: dict[str, YamlProcessUnit] = {}
+    def process_units(self) -> dict[str, YamlProcessUnitDefinition]:
+        process_units: dict[str, YamlProcessUnitDefinition] = {}
         raw = self._get_yaml_dict_or_empty(_PROCESS_UNITS_KEY)
 
         for name, unit_data in raw.items():
             try:
-                process_units[name] = TypeAdapter(YamlProcessUnit).validate_python(unit_data)
+                process_units[name] = TypeAdapter(YamlProcessUnitDefinition).validate_python(unit_data)
             except PydanticValidationError:
                 pass
         return process_units

src/libecalc/presentation/yaml/yaml_models/yaml_model.py

@@ -23,7 +23,7 @@
     YamlProcessSimulation,
     YamlPumpProcessSimulation,
 )
-from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnit
+from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnitDefinition
 from libecalc.presentation.yaml.yaml_types.streams.yaml_inlet_stream import YamlInletStream
 from libecalc.presentation.yaml.yaml_types.time_series.yaml_time_series import (
     YamlTimeSeriesCollection,
@@ -90,7 +90,7 @@ def inlet_streams(self) -> dict[str, YamlInletStream]:
 
     @property
     @abc.abstractmethod
-    def process_units(self) -> dict[str, YamlProcessUnit]:
+    def process_units(self) -> dict[str, YamlProcessUnitDefinition]:
         pass
 
     @property

src/libecalc/presentation/yaml/yaml_reference_service.py

@@ -30,7 +30,7 @@
     YamlProcessSimulation,
     YamlPumpProcessSimulation,
 )
-from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnit
+from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnitDefinition
 from libecalc.presentation.yaml.yaml_types.streams.yaml_inlet_stream import YamlInletStream
 
 logger = logging.getLogger(__name__)
@@ -44,7 +44,7 @@
     | YamlProcessPipeline
     | YamlProcessSimulation
     | YamlPumpProcessSimulation
-    | YamlProcessUnit
+    | YamlProcessUnitDefinition
 )
 
 # Some models are referenced by other models, for example a compressor model will reference compressor chart models
@@ -218,8 +218,8 @@ def get_stream(self, reference: str) -> YamlInletStream:
             raise InvalidReferenceException("stream", reference)
         return model
 
-    def get_process_unit(self, reference: str) -> YamlProcessUnit:
+    def get_process_unit(self, reference: str) -> YamlProcessUnitDefinition:
         model = self._resolve_yaml_reference(reference, "process unit")
-        if not isinstance(model, get_args(get_args(YamlProcessUnit)[0])):
+        if not isinstance(model, get_args(get_args(YamlProcessUnitDefinition)[0])):
             raise InvalidReferenceException("process unit", reference)
         return model

src/libecalc/presentation/yaml/yaml_types/components/yaml_asset.py

@@ -14,7 +14,7 @@
     YamlProcessSimulation,
     YamlPumpProcessSimulation,
 )
-from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnit
+from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import YamlProcessUnitDefinition
 from libecalc.presentation.yaml.yaml_types.streams.yaml_inlet_stream import YamlInletStream
 from libecalc.presentation.yaml.yaml_types.time_series.yaml_time_series import YamlTimeSeriesCollection
 from libecalc.presentation.yaml.yaml_types.yaml_default_datetime import YamlDefaultDatetime
@@ -69,7 +69,7 @@ class YamlAsset(YamlBase):
         description="Defines variables used in an energy usage model by means of expressions or constants."
         "\n\n$ECALC_DOCS_KEYWORDS_URL/VARIABLES",
     )
-    process_units: dict[str, YamlProcessUnit] = Field(
+    process_units: dict[str, YamlProcessUnitDefinition] = Field(
         default_factory=dict,
         title="PROCESS_UNITS",
         description="Defines process units used in PROCESS_PIPELINES.",

src/libecalc/presentation/yaml/yaml_types/process/yaml_process_pipeline.py

@@ -1,23 +1,23 @@
 from enum import StrEnum
-from typing import Annotated, Literal, TypeVar
+from typing import Annotated, TypeVar
 
 from pydantic import Field
 
 from libecalc.presentation.yaml.yaml_types import YamlBase
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_references import (
-    ProcessEventReference,
-    ProcessUnitReference,
+    DefinitionReference,
+    InstanceReference,
 )
 from libecalc.presentation.yaml.yaml_types.process.yaml_process_units import (
-    YamlProcessUnit,
+    YamlProcessUnitDefinition,
 )
 
 TTarget = TypeVar("TTarget")
 
 
-class YamlItem[TTarget](YamlBase):
-    target: TTarget | ProcessUnitReference
-    name: str | None = None
+class YamlProcessUnitInstance[TTarget](YamlBase):
+    target: TTarget | DefinitionReference
+    name: InstanceReference | None = None
 
 
 class PipelineEventAction(StrEnum):
@@ -39,21 +39,21 @@ class YamlPipelineEvent(YamlBase):
         ),
     ]
     change_target: Annotated[
-        ProcessUnitReference,
+        InstanceReference,
         Field(
             title="CHANGE_TARGET",
             description="Name of the process unit in the pipeline to change.",
         ),
     ]
     change_from: Annotated[
-        ProcessUnitReference,
+        DefinitionReference,
         Field(
             title="CHANGE_FROM",
             description="Reference to the existing process unit template being replaced.",
         ),
     ]
     change_to: Annotated[
-        ProcessUnitReference,
+        DefinitionReference,
         Field(
             title="CHANGE_TO",
             description="Reference to the new process unit template to use.",
@@ -67,7 +67,7 @@ class YamlPipelineEvent(YamlBase):
         ),
     ]
     ref: Annotated[
-        ProcessEventReference,
+        InstanceReference,
         Field(
             title="REF",
             description="Reference to a PROCESS_EVENT by name.",
@@ -76,9 +76,8 @@ class YamlPipelineEvent(YamlBase):
 
 
 class YamlProcessPipeline(YamlBase):
-    type: Literal["SERIAL"]
-    name: str
-    items: list[YamlItem[YamlProcessUnit]]
+    name: InstanceReference
+    process_units: list[YamlProcessUnitInstance[YamlProcessUnitDefinition]]
     events: Annotated[
         list[YamlPipelineEvent],
         Field(

src/libecalc/presentation/yaml/yaml_types/process/yaml_process_references.py

@@ -2,9 +2,5 @@
 Shared reference type aliases for YAML process types.
 """
 
-type StreamRef = str
-type ProcessPipelineReference = str  # TODO: validate correct reference
-type ProcessUnitReference = str
-type EcalcEventReference = str
-type ProcessEventReference = str
-type PumpChartReference = str
+type InstanceReference = str
+type DefinitionReference = str