fix: clarify difference between instance and definition references

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