Interface ProcessEquipmentInterface

All Superinterfaces:
NamedInterface, ProcessElementInterface, Runnable, Serializable, SimulationInterface
All Known Subinterfaces:
AbsorberInterface, CompressorInterface, DistillationInterface, ExpanderInterface, MixerInterface, ModuleInterface, MultiStreamHeatExchangerInterface, PumpInterface, SplitterInterface, StreamInterface, TrayInterface, ValveInterface
All Known Implementing Classes:
AdiabaticPipe, AdiabaticTwoPhasePipe, Adjuster, AdsorptionBed, AdsorptionDehydrationlModule, AirCooler, AmmoniaSynthesisReactor, AnaerobicDigester, AnnularLeakagePath, BatteryStorage, BiogasUpgrader, BiomassGasifier, BlackOilSeparator, BlowdownValve, Calculator, CementDegradationModel, CharCoalFilter, CheckValve, CO2Electrolyzer, CO2RemovalModule, CombinedCycleSystem, ComponentSplitter, Compressor, CompressorTrain, Condenser, ControlValve, Cooler, CryogenicSeparator, Crystallizer, DexpiProcessUnit, DexpiProcessUnit, DexpiStream, DexpiStream, DistillationColumn, DPCUModule, Dryer, Ejector, Electrolyzer, EndFlash, EnzymeTreatment, EquilibriumStream, ESDValve, ESPPump, Expander, ExpanderOld, FermentationReactor, Fermenter, Filter, FiredHeater, Flare, FlareStack, FlexiblePipe, FloatingSubstructure, FlowRateAdjuster, FlowSetter, FuelCell, FuelGasSystem, FurnaceBurner, GasFlotationUnit, GasScrubber, GasScrubberSimple, GasTurbine, GibbsReactor, GibbsReactorCO2, GlycolDehydrationlModule, GORfitter, H2SScavenger, Heater, HeatExchanger, HIPPSValve, HRSG, Hydrocyclone, Hydrocyclone, IncompressiblePipeFlow, InjectionConformanceMonitor, IronIonSaturationStream, LevelControlValve, LiquidLiquidExtractor, LNGAgeingScenario, LNGHeatExchanger, LNGTank, LoopedPipeNetwork, Manifold, MEGReclaimerModule, MembraneSeparator, MercuryRemovalBed, Mixer, MixerGasProcessingModule, MoleFractionControllerUtil, MooringSystem, MPFMfitter, MultiCompartmentReservoir, MultiEffectEvaporator, MultiphasePipe, MultiPortEquipment, MultiStreamHeatExchanger, MultiStreamHeatExchanger2, MultiVariableAdjuster, NeqGasScrubber, NeqHeater, NeqSimUnit, NeqStream, OffshoreEnergySystem, OnePhasePipeLine, Orifice, PackedColumn, PipeBeggsAndBrills, PipeFlowNetwork, PipeHagedornBrown, Pipeline, PipeMukherjeeAndBrill, PLEM, PLET, PlugFlowReactor, PressureControlValve, PressureDrop, PressureFilter, ProcessEquipmentBaseClass, ProcessModuleBaseClass, ProducedWaterTreatmentTrain, PropaneCoolingModule, PSDValve, Pump, PyrolysisReactor, RateBasedAbsorber, RateBasedPackedColumn, ReactiveTray, Reboiler, ReBoiler, Recycle, ReservoirCVDsim, ReservoirDiffLibsim, ReservoirTPsim, Riser, RotaryVacuumFilter, RuptureDisk, SafetyReliefValve, SafetyValve, ScalePotentialCheckStream, ScrewPress, ScrubColumn, SeparationTrainModule, SeparationTrainModuleSimple, Separator, SetPoint, Setter, ShortcutDistillationColumn, SimpleAbsorber, SimpleAdsorber, SimpleAmineAbsorber, SimpleFlowLine, SimpleReservoir, SimpleTEGAbsorber, SimpleTPoutPipeline, SimpleTray, SolarPanel, SolidsCentrifuge, SolidsSeparator, Splitter, SpreadsheetBlock, StaticMixer, StaticNeqMixer, StaticPhaseMixer, SteamHeater, SteamTurbine, StirredTankReactor, Stream, StreamSaturatorUtil, StreamTransition, SubseaBooster, SubseaJumper, SubseaManifold, SubseaPowerCable, SubseaTree, SubseaWell, SulfurDepositionAnalyser, SulfurFilter, Tank, ThreePhaseSeparator, ThrottlingValve, TopsidePiping, TransientPipe, TransientWellbore, TubingPerformance, TubingPerformance, TurboExpanderCompressor, TwoFluidPipe, TwoPhasePipeLine, TwoPhaseSeparator, TwoPortEquipment, Umbilical, UnisimCalculator, UtilityAirSystem, VesselDepressurization, VirtualStream, VLSolidTray, WaterCooler, WaterHammerPipe, WaterStripperColumn, WellFlow, WellFlowlineNetwork, WellFluidModule, WellSystem, WindFarm, WindTurbine
public interface ProcessEquipmentInterface extends ProcessElementInterface, SimulationInterface

ProcessEquipmentInterface interface.

Version:
$Id: $Id
Author:
Even Solbraa

  • Method Details

    • reportResults

      String[][] reportResults()

      reportResults.

      Returns:
      an array of String objects

    • initMechanicalDesign

      default void initMechanicalDesign()

      Initialize a initMechanicalDesign for the equipment.

    • getMechanicalDesign

      MechanicalDesign getMechanicalDesign()

      Get a mechanicalDesign for the equipment.

      Returns:
      a MechanicalDesign object

    • initElectricalDesign

      default void initElectricalDesign()

      Initialize an electricalDesign for the equipment.

    • getElectricalDesign

      default ElectricalDesign getElectricalDesign()

      Get an electricalDesign for the equipment.

      Returns:
      a ElectricalDesign object

    • initInstrumentDesign

      default void initInstrumentDesign()
      Initialize an instrumentDesign for the equipment.

    • getInstrumentDesign

      default InstrumentDesign getInstrumentDesign()
      Get an instrumentDesign for the equipment.
      Returns:
      a InstrumentDesign object

    • needRecalculation

      default boolean needRecalculation()

      Check if process equipment needs recalculating.

      Returns:
      true or false

    • getSpecification

      String getSpecification()

      getSpecification.

      Returns:
      a String object

    • setSpecification

      void setSpecification(String specification)

      setSpecification.

      Parameters:
      specification - a String object

    • displayResult

      void displayResult()

      displayResult.

    • setRegulatorOutSignal

      void setRegulatorOutSignal(double signal)

      setRegulatorOutSignal.

      Parameters:
      signal - a double

    • setController

      void setController(ControllerDeviceInterface controller)

      setController.

      Parameters:
      controller - a ControllerDeviceInterface object

    • getController

      ControllerDeviceInterface getController()

      getController.

      Returns:
      a ControllerDeviceInterface object

    • addController

      default void addController(String tag, ControllerDeviceInterface controller)
      Adds a controller to this equipment with the given tag name.
      Parameters:
      tag - a unique tag identifying the controller (e.g. "PC-101", "LC-101")
      controller - a ControllerDeviceInterface object

    • getController

      default ControllerDeviceInterface getController(String tag)
      Gets a controller by tag name.
      Parameters:
      tag - the controller tag name
      Returns:
      the controller, or null if not found

    • getControllers

      default Collection<ControllerDeviceInterface> getControllers()
      Gets all controllers attached to this equipment.
      Returns:
      unmodifiable collection of controllers

    • getInletStreams

      default List<StreamInterface> getInletStreams()
      Returns all inlet streams connected to this equipment. Subclasses override to report their specific inlets. Used by graph builders, DEXPI export, and auto-instrumentation to discover topology without instanceof checks.
      Returns:
      unmodifiable list of inlet streams (empty by default)

    • getOutletStreams

      default List<StreamInterface> getOutletStreams()
      Returns all outlet streams produced by this equipment. Subclasses override to report their specific outlets. Used by graph builders, DEXPI export, and auto-instrumentation to discover topology without instanceof checks.
      Returns:
      unmodifiable list of outlet streams (empty by default)

    • getFluid

      default SystemInterface getFluid()

      getFluid.

      Returns:
      a SystemInterface object

    • getThermoSystem

      SystemInterface getThermoSystem()

      getThermoSystem.

      Returns:
      a SystemInterface object

    • getMassBalance

      double getMassBalance()

      getMassBalance in kg/sec.

      Returns:
      The mass balance of the process equipment in kg/sec.

    • getPressure

      double getPressure()

      Getter for the field pressure.

      Returns:
      Pressure in bara

    • getPressure

      double getPressure(String unit)

      Getter for the field pressure converted to specified unit.

      Parameters:
      unit - a String object
      Returns:
      a double

    • getTemperature

      double getTemperature(String unit)

      Getter for the field temperature converted to specified unit.

      Parameters:
      unit - a String object
      Returns:
      a double

    • getTemperature

      double getTemperature()

      Getter for the field temperature.

      Returns:
      a double

    • setPressure

      void setPressure(double pressure)

      Setter for the field pressure.

      Parameters:
      pressure - a double

    • setTemperature

      void setTemperature(double temperature)

      Setter for the field temperature.

      Parameters:
      temperature - Temperature in Kelvin

    • runConditionAnalysis

      void runConditionAnalysis(ProcessEquipmentInterface refExchanger)

      runConditionAnalysis.

      Parameters:
      refExchanger - a ProcessEquipmentInterface object

    • getConditionAnalysisMessage

      String getConditionAnalysisMessage()

      getConditionAnalysisMessage.

      Returns:
      a String object

    • getExergyChange

      double getExergyChange(String unit, double surroundingTemperature)
      Get exergy change production of the process equipment.
      Parameters:
      unit - Supported units are J and kJ
      surroundingTemperature - The surrounding temperature in Kelvin
      Returns:
      change in exergy in specified unit

    • getResultTable

      String[][] getResultTable()

      getResultTable.

      Returns:
      an array of String objects

    • equals

      boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      int hashCode()
      Overrides:
      hashCode in class Object

    • toJson

      String toJson()

      Serializes the Process Equipment along with its state to a JSON string.

      Returns:
      json string.

    • toJson

      default String toJson(ReportConfig cfg)
      Serializes the Process Equipment with configurable level of detail.
      Parameters:
      cfg - report configuration
      Returns:
      json string

    • getReport_json

      String getReport_json()

      getReport_json.

      Return results of simulation in json format
      Specified by:
      getReport_json in interface SimulationInterface
      Returns:
      a String

    • getEntropyProduction

      default double getEntropyProduction(String unit)

      getEntropyProduction.

      Parameters:
      unit - a String object
      Returns:
      a double

    • getMassBalance

      default double getMassBalance(String unit)

      getMassBalance.

      Parameters:
      unit - a String object
      Returns:
      a double

    • getExergyChange

      default double getExergyChange(String unit)

      getExergyChange.

      Parameters:
      unit - a String object
      Returns:
      a double

    • getExergyDestruction

      default double getExergyDestruction(String unit, double surroundingTemperature)
      Exergy destruction rate of the unit operation, based on the universal relation E_destroyed = T0 * S_gen where S_gen is the entropy generation across the unit and T0 is the surrounding ("dead state") temperature. The returned value is always non-negative.

      The default implementation uses getEntropyProduction(String) expressed in J/K. For adiabatic equipment (valves, separators, mixers, compressors, pumps) this gives the exact exergy destruction. For units with heat crossing the boundary at a known source temperature (heaters, coolers), override this method to include the Carnot-weighted heat exergy.

      Parameters:
      unit - target unit, one of J, kJ, MJ, W, kW, MW
      surroundingTemperature - surrounding (dead-state) temperature in K
      Returns:
      non-negative exergy destruction rate in the requested unit

    • getExergyDestruction

      default double getExergyDestruction(String unit)
      Exergy destruction rate with a default surrounding temperature of 288.15 K (15 degC). See getExergyDestruction(String, double) for details.
      Parameters:
      unit - target unit
      Returns:
      exergy destruction in the requested unit

    • getCapacityDuty

      default double getCapacityDuty()

      getCapacityDuty.

      Returns:
      a double

    • getCapacityMax

      default double getCapacityMax()

      getCapacityMax.

      Returns:
      a double

    • getRestCapacity

      default double getRestCapacity()

      getRestCapacity.

      Returns:
      a double

    • validateSetup

      default ValidationResult validateSetup()
      Validate the process equipment before execution.

      Checks for common setup errors:

      • Equipment has a valid name
      • Input streams connected
      • Operating parameters in valid ranges
      Returns:
      validation result with errors and warnings

    • isSimulationValid

      default boolean isSimulationValid()
      Checks if the current simulation result is physically valid.

      Returns false if calculated values are outside physically possible ranges. This method should be overridden by specific equipment types to perform equipment-specific validation. For example:

      • Compressor: power must be positive, head must be positive
      • Heat exchanger: duty direction must match temperature change
      • Separator: phase fractions must sum to 1.0
      Returns:
      true if simulation results are physically valid, false otherwise

    • getSimulationValidationErrors

      default List<String> getSimulationValidationErrors()
      Gets validation errors for the current simulation state.

      Returns a list of human-readable error messages describing why the simulation result is invalid. Returns an empty list if the simulation is valid.

      Returns:
      list of validation error messages, empty if valid

    • isWithinOperatingEnvelope

      default boolean isWithinOperatingEnvelope()
      Checks if the equipment is operating within its valid operating envelope.

      This is different from capacity utilization - it checks whether the equipment can physically operate at the current conditions, not whether it's operating efficiently. For example:

      • Compressor: checks if between surge and stonewall
      • Pump: checks if above minimum flow (no cavitation)
      • Heat exchanger: checks if approach temperature is positive
      Returns:
      true if operating within valid envelope

    • getOperatingEnvelopeViolation

      default String getOperatingEnvelopeViolation()
      Gets the reason why equipment is outside its operating envelope.
      Returns:
      description of envelope violation, or null if within envelope

    • getOutletTemperature

      default double getOutletTemperature(String unit)
      Returns the temperature of the primary outlet stream in the specified unit.

      Works uniformly across all equipment types by using getOutletStreams(). For equipment with multiple outlets (e.g., separators), returns the first outlet's temperature.

      Parameters:
      unit - temperature unit, e.g. "C", "K"
      Returns:
      outlet temperature in specified unit, or Double.NaN if no outlet streams

    • getOutletPressure

      default double getOutletPressure(String unit)
      Returns the pressure of the primary outlet stream in the specified unit.

      Works uniformly across all equipment types by using getOutletStreams(). For equipment with multiple outlets, returns the first outlet's pressure.

      Parameters:
      unit - pressure unit, e.g. "bara", "barg", "Pa"
      Returns:
      outlet pressure in specified unit, or Double.NaN if no outlet streams

    • getOutletFlowRate

      default double getOutletFlowRate(String unit)
      Returns the total flow rate across all outlet streams in the specified unit.

      For single-outlet equipment (compressor, heater, valve), returns the outlet flow rate. For multi-outlet equipment (separator), returns the sum of all outlet flow rates.

      Parameters:
      unit - flow unit, e.g. "kg/hr", "Sm3/hr", "m3/hr"
      Returns:
      total outlet flow rate in specified unit, or Double.NaN if no outlet streams

    • getEquipmentState

      default Map<String, Map<String,Object>> getEquipmentState(String temperatureUnit, String pressureUnit, String flowUnit)
      Returns a map of key equipment properties with values and units.

      Provides a unified way to access equipment state without knowing the specific equipment type. Each entry in the outer map has a property name (e.g. "temperature", "pressure"). Each inner map contains "value" (Double) and "unit" (String).

      The default implementation uses getOutletStreams() to report outlet conditions. Subclasses override this to add equipment-specific properties (e.g., valve opening, compressor power, separator liquid levels).

      Parameters:
      temperatureUnit - temperature unit (e.g. "C")
      pressureUnit - pressure unit (e.g. "bara")
      flowUnit - flow unit (e.g. "kg/hr")
      Returns:
      map of property name to value/unit maps

    • createStateEntry

      static Map<String,Object> createStateEntry(double value, String unit)
      Helper to create a state entry map with value and unit.
      Parameters:
      value - the numeric value
      unit - the unit string
      Returns:
      map with "value" and "unit" keys

    • getReferenceDesignation

      default ReferenceDesignation getReferenceDesignation()
      Returns the IEC 81346 reference designation for this equipment.

      The reference designation encodes three aspects per IEC 81346: function (what the system does), product (what the equipment is), and location (where it is installed).

      Returns:
      the reference designation object, never null

    • setReferenceDesignation

      default void setReferenceDesignation(ReferenceDesignation referenceDesignation)
      Sets the IEC 81346 reference designation for this equipment.
      Parameters:
      referenceDesignation - the reference designation to set

    • getReferenceDesignationString

      default String getReferenceDesignationString()
      Returns the full IEC 81346 reference designation string.

      Convenience method equivalent to getReferenceDesignation().toReferenceDesignationString().

      Returns:
      the formatted reference designation string, e.g. "=A1.K1-B1+P1.M1"

    • getCapacityConstraints

      default Map<String, CapacityConstraint> getCapacityConstraints()
      Gets all capacity constraints defined for this equipment.

      Returns an unmodifiable map of constraint name to constraint object. Constraints are used by the optimization framework to detect bottlenecks, enforce limits, and guide production allocation. Equipment subclasses populate this map via addCapacityConstraint(CapacityConstraint).

      Returns:
      unmodifiable map of constraint name to constraint, empty if none defined

    • addCapacityConstraint

      default void addCapacityConstraint(CapacityConstraint constraint)
      Adds a capacity constraint to this equipment.

      Constraints can be added at any time. If a constraint with the same name already exists, it is replaced. Use the fluent builder API on CapacityConstraint to configure the constraint before adding.

      Parameters:
      constraint - the capacity constraint to add (ignored if null)

    • getBottleneckConstraint

      default CapacityConstraint getBottleneckConstraint()
      Gets the bottleneck (most limiting) constraint for this equipment.

      Returns the enabled constraint with the highest utilization ratio. If no constraints are defined or enabled, returns null.

      Returns:
      the most limiting constraint, or null if none

    • isCapacityExceeded

      default boolean isCapacityExceeded()
      Checks if any capacity constraint is violated (exceeds 100% utilization).

      A violated constraint means the equipment is operating beyond its design capacity. For HARD constraints, this may indicate equipment trip or failure. For SOFT constraints, this indicates reduced efficiency or accelerated wear.

      Returns:
      true if any enabled constraint utilization exceeds 1.0 (100%)

    • isHardLimitExceeded

      default boolean isHardLimitExceeded()
      Checks if any HARD constraint limit is exceeded.

      HARD limits represent absolute equipment limits (e.g., maximum speed) that cannot be exceeded without equipment trip or damage. This is more severe than general capacity exceedance.

      Returns:
      true if any enabled HARD constraint's max value is exceeded

    • getMaxUtilization

      default double getMaxUtilization()
      Gets the maximum utilization across all enabled constraints.

      Returns the highest utilization ratio across all enabled constraints. Values above 1.0 indicate the equipment is over capacity. Returns 0.0 if no constraints are defined or enabled.

      Returns:
      maximum utilization as fraction (1.0 = 100% of design capacity)

    • getMaxUtilizationPercent

      default double getMaxUtilizationPercent()
      Gets the maximum utilization as a percentage.
      Returns:
      maximum utilization as percentage (100.0 = 100% of design capacity)

    • getAvailableMargin

      default double getAvailableMargin()
      Gets the available margin (headroom) on the most limiting constraint.

      Returns the remaining capacity before the bottleneck constraint reaches 100%. Negative values indicate the equipment is already over capacity.

      Returns:
      available margin as fraction (0.2 = 20% headroom remaining)

    • getAvailableMarginPercent

      default double getAvailableMarginPercent()
      Gets the available margin as a percentage.
      Returns:
      available margin as percentage

    • isNearCapacityLimit

      default boolean isNearCapacityLimit()
      Checks if any enabled constraint is near its limit (above warning threshold).

      The warning threshold is typically set at 90% of design capacity to provide early warning before constraints are violated.

      Returns:
      true if any enabled constraint is above its warning threshold

    • getUtilizationSummary

      default Map<String,Double> getUtilizationSummary()
      Gets a summary of all enabled constraint utilizations.

      Returns a map of constraint names to their current utilization percentages. Useful for reporting and visualization.

      Returns:
      map of constraint name to utilization percentage