Class ProcessAutomation

java.lang.Object
neqsim.process.automation.ProcessAutomation
public class ProcessAutomation extends Object
Provides a stable, string-addressable automation API for interacting with a running NeqSim ProcessSystem or ProcessModel. Variables in the simulation are reachable through stable dot-notation paths such as "separator-1.gasOutStream.temperature", removing the need to navigate Java objects directly.

When backed by a ProcessModel (multi-area plant), addresses use area-qualified syntax: "AreaName::UnitName.property" or "AreaName::UnitName.port.property".

The core operations are:

Address format: unitName.property or unitName.streamPort.property

Example usage: 

// Single ProcessSystem
ProcessAutomation auto = new ProcessAutomation(process);

// List all units
List<String> units = auto.getUnitList();

// List variables for a separator
List<SimulationVariable> vars = auto.getVariableList("HP Sep");

// Read a value
double temp = auto.getVariableValue("HP Sep.gasOutStream.temperature", "C");

// Set an input
auto.setVariableValue("Compressor.outletPressure", 120.0, "bara");

// Multi-area ProcessModel
ProcessAutomation plantAuto = new ProcessAutomation(plantModel);
List<String> areas = plantAuto.getAreaList();
List<String> areaUnits = plantAuto.getUnitList("Separation");
double p = plantAuto.getVariableValue("Separation::HP Sep.pressure", "bara");
Version:
1.0
Author:
Even Solbraa

  • Field Details

  • Constructor Details

    • ProcessAutomation

      public ProcessAutomation(ProcessSystem processSystem)
      Creates an automation facade for a single process system.
      Parameters:
      processSystem - the process system to automate

    • ProcessAutomation

      public ProcessAutomation(ProcessModel processModel)
      Creates an automation facade for a multi-area process model.

      In this mode, addresses use area-qualified syntax: "AreaName::UnitName.property".

      Parameters:
      processModel - the process model to automate

  • Method Details

    • isMultiArea

      public boolean isMultiArea()
      Returns whether this automation facade is backed by a ProcessModel (multi-area).
      Returns:
      true if backed by a ProcessModel, false if backed by a single ProcessSystem

    • getDiagnostics

      public AutomationDiagnostics getDiagnostics()
      Returns the diagnostics instance for this automation facade. The diagnostics provide fuzzy name matching, auto-correction, physical value validation, and operation history tracking.
      Returns:
      the automation diagnostics

    • getVariableValueSafe

      public String getVariableValueSafe(String address, String unitOfMeasure)
      Reads a variable value with self-healing: if the exact address fails, attempts auto-correction via fuzzy matching against known unit names and variable addresses. Returns a JSON string with the value on success, or a diagnostic result with suggestions on failure.
      Parameters:
      address - the dot-notation address, e.g. "separator-1.gasOutStream.temperature"
      unitOfMeasure - the desired unit
      Returns:
      JSON result string with either value or diagnostic information

    • setVariableValueSafe

      public String setVariableValueSafe(String address, double value, String unitOfMeasure)
      Sets a variable value with self-healing: if the exact address fails, attempts auto-correction via fuzzy matching. Also validates the value against physical bounds before setting.
      Parameters:
      address - the dot-notation address
      value - the value to set
      unitOfMeasure - the unit of the value
      Returns:
      JSON result string with either success or diagnostic information

    • getAreaList

      public List<String> getAreaList()
      Returns the names of all process areas. Only available when backed by a ProcessModel.
      Returns:
      unmodifiable list of area names in insertion order
      Throws:
      IllegalStateException - if backed by a single ProcessSystem

    • getUnitList

      public List<String> getUnitList()
      Returns the names of all unit operations. When backed by a ProcessModel, returns area-qualified names in the format "AreaName::UnitName".
      Returns:
      unmodifiable list of unit operation names

    • getUnitList

      public List<String> getUnitList(String areaName)
      Returns the names of unit operations in a specific process area. Only available when backed by a ProcessModel.
      Parameters:
      areaName - the name of the process area
      Returns:
      unmodifiable list of unit operation names (without area prefix)
      Throws:
      IllegalStateException - if backed by a single ProcessSystem
      IllegalArgumentException - if the area is not found

    • getVariableList

      public List<SimulationVariable> getVariableList(String unitName)
      Returns all available variables for the named unit operation.
      Parameters:
      unitName - the name of the unit operation
      Returns:
      list of variable descriptors
      Throws:
      IllegalArgumentException - if the unit is not found

    • getVariableList

      public List<SimulationVariable> getVariableList(String unitName, SimulationVariable.VariableType type)
      Returns variables for the named unit, filtered by type.

      When backed by a ProcessModel, the unitName may be area-qualified: "AreaName::UnitName".

      Parameters:
      unitName - the name of the unit operation, optionally area-qualified
      type - the variable type filter, or null for all variables
      Returns:
      list of variable descriptors matching the filter
      Throws:
      IllegalArgumentException - if the unit is not found

    • getEquipmentType

      public String getEquipmentType(String unitName)
      Returns the simple class name (equipment type) of a unit operation. Useful for discovering what kind of equipment a unit is, e.g. "Compressor", "Separator", "PipeBeggsAndBrills".
      Parameters:
      unitName - the name of the unit operation, optionally area-qualified
      Returns:
      the simple class name of the equipment
      Throws:
      IllegalArgumentException - if the unit is not found

    • getVariableValue

      public double getVariableValue(String address, String unitOfMeasure)
      Reads the current value of a simulation variable.

      When backed by a ProcessModel, the address must be area-qualified: "AreaName::unitName.property" or "AreaName::unitName.streamPort.property".

      Parameters:
      address - the dot-notation address, e.g. "separator-1.gasOutStream.temperature" or "Separation::separator-1.gasOutStream.temperature"
      unitOfMeasure - the desired unit, e.g. "C", "bara", "kg/hr". Pass null or empty for default units
      Returns:
      the variable value in the requested unit
      Throws:
      IllegalArgumentException - if the address cannot be resolved

    • setVariableValue

      public void setVariableValue(String address, double value, String unitOfMeasure)
      Sets the value of a simulation input variable. Only variables with INPUT type can be set.

      When backed by a ProcessModel, the address must be area-qualified: "AreaName::Compressor.outletPressure".

      Parameters:
      address - the dot-notation address, e.g. "Compressor.outletPressure" or "Compression::Compressor.outletPressure"
      value - the value to set
      unitOfMeasure - the unit of the provided value, e.g. "bara", "C". Pass null or empty for default units
      Throws:
      IllegalArgumentException - if the address cannot be resolved or the variable is read-only

    • resolveUnit

      private ProcessAutomation.ResolvedUnit resolveUnit(String unitName)
      Resolves a unit name (optionally area-qualified) to the equipment and its address prefix.
      Parameters:
      unitName - the unit name, optionally with area prefix "AreaName::UnitName"
      Returns:
      the resolved unit and address prefix
      Throws:
      IllegalArgumentException - if the unit is not found

    • findUnit

      private ProcessEquipmentInterface findUnit(String areaName, String unitName)
      Finds a unit by name, optionally scoped to a specific area.
      Parameters:
      areaName - the area name, or null to search the single ProcessSystem (or all areas)
      unitName - the unit name
      Returns:
      the equipment
      Throws:
      IllegalArgumentException - if the unit is not found

    • getPlainUnitNames

      private List<String> getPlainUnitNames(ProcessSystem ps)
      Gets plain (non-area-qualified) unit names from a ProcessSystem.
      Parameters:
      ps - the process system
      Returns:
      list of unit names

    • findByReferenceDesignation

      private ProcessEquipmentInterface findByReferenceDesignation(String areaName, String refDesString)
      Finds a unit by its IEC 81346 reference designation string.

      Searches all equipment in the relevant process system(s) for a matching reference designation. This enables addressing equipment by their IEC 81346 codes, e.g. "=A1-B1" or "-K2".

      Parameters:
      areaName - the area name to search within (null to search all)
      refDesString - the reference designation string to match
      Returns:
      the matching equipment, or null if not found

    • searchByRefDes

      private ProcessEquipmentInterface searchByRefDes(ProcessSystem ps, String refDesString)
      Searches a process system for equipment matching a reference designation string.
      Parameters:
      ps - the process system to search
      refDesString - the reference designation to match
      Returns:
      the matching equipment, or null if not found

    • buildVariableList

      private List<SimulationVariable> buildVariableList(String unitName, ProcessEquipmentInterface unit)
      Builds the list of variables exposed by a unit operation.
      Parameters:
      unitName - the unit name (used as address prefix)
      unit - the unit operation
      Returns:
      list of variables

    • addStreamVariables

      private void addStreamVariables(List<SimulationVariable> vars, String prefix, StreamInterface stream, boolean isInput)
      Adds stream variables (temperature, pressure, flowRate) with appropriate INPUT/OUTPUT type.
      Parameters:
      vars - the list to add to
      prefix - the address prefix
      stream - the stream
      isInput - whether the stream properties are settable

    • addStreamOutputVariables

      private void addStreamOutputVariables(List<SimulationVariable> vars, String prefix, StreamInterface stream)
      Adds read-only stream variables for an output stream.
      Parameters:
      vars - the list to add to
      prefix - the address prefix including port name
      stream - the stream

    • addOutletStreamVariables

      private void addOutletStreamVariables(List<SimulationVariable> vars, String unitName, ProcessEquipmentInterface unit)
      Adds outlet stream variables for single-outlet equipment.
      Parameters:
      vars - the list to add to
      unitName - the unit name
      unit - the equipment

    • getEquipmentProperty

      private double getEquipmentProperty(ProcessEquipmentInterface unit, String property, String uom)
      Gets a property value directly from an equipment object.
      Parameters:
      unit - the equipment
      property - the property name
      uom - the desired unit of measure
      Returns:
      the property value

    • setEquipmentProperty

      private void setEquipmentProperty(ProcessEquipmentInterface unit, String property, double value, String uom)
      Sets a property value directly on an equipment object.
      Parameters:
      unit - the equipment
      property - the property name
      value - the value to set
      uom - the unit of measure for the value

    • resolveStreamPort

      private StreamInterface resolveStreamPort(ProcessEquipmentInterface unit, String portName)
      Resolves a stream port name to the actual stream object.
      Parameters:
      unit - the equipment
      portName - the port name, e.g. "gasOutStream", "liquidOutStream", "outletStream"
      Returns:
      the resolved stream, or null if not found

    • getStreamProperty

      private double getStreamProperty(StreamInterface stream, String property, String uom)
      Gets a property value from a stream.
      Parameters:
      stream - the stream
      property - the property name
      uom - the desired unit of measure
      Returns:
      the property value

    • setStreamProperty

      private void setStreamProperty(StreamInterface stream, String property, double value, String uom)
      Sets a property value on a stream.
      Parameters:
      stream - the stream
      property - the property name
      value - the value to set
      uom - the unit of measure

    • diagnoseAndAttemptRecovery

      private AutomationDiagnostics.DiagnosticResult diagnoseAndAttemptRecovery(String address, IllegalArgumentException error)
      Diagnoses an address resolution failure and attempts recovery via fuzzy matching.
      Parameters:
      address - the failed address
      error - the caught exception
      Returns:
      a diagnostic result with suggestions and possible auto-correction

    • extractPropertyName

      private String extractPropertyName(String address)
      Extracts the property name from an address (the last dot-separated segment).
      Parameters:
      address - the dot-notation address
      Returns:
      the property name

    • buildSuccessJson

      private String buildSuccessJson(String address, double value, String unit)
      Builds a success JSON response for a get operation.
      Parameters:
      address - the address
      value - the value
      unit - the unit of measure
      Returns:
      JSON string

    • buildAutoCorrectedJson

      private String buildAutoCorrectedJson(String originalAddress, String correctedAddress, double value, String unit, AutomationDiagnostics.DiagnosticResult diag)
      Builds a JSON response for a successful auto-corrected get operation.
      Parameters:
      originalAddress - the original address that failed
      correctedAddress - the corrected address that succeeded
      value - the value read
      unit - the unit of measure
      diag - the diagnostic result
      Returns:
      JSON string

    • buildSetSuccessJson

      private String buildSetSuccessJson(String address, double value, String unit, String warningJson)
      Builds a success JSON response for a set operation.
      Parameters:
      address - the address
      value - the value set
      unit - the unit of measure
      warningJson - JSON warning from bounds validation, or null
      Returns:
      JSON string

    • buildAutoCorrectedSetJson

      private String buildAutoCorrectedSetJson(String originalAddress, String correctedAddress, double value, String unit, AutomationDiagnostics.DiagnosticResult diag)
      Builds a JSON response for a successful auto-corrected set operation.
      Parameters:
      originalAddress - the original address that failed
      correctedAddress - the corrected address that succeeded
      value - the value set
      unit - the unit of measure
      diag - the diagnostic result
      Returns:
      JSON string