Class MultiVariableAdjuster

java.lang.Object
neqsim.util.NamedBaseClass
neqsim.process.SimulationBaseClass
neqsim.process.equipment.ProcessEquipmentBaseClass
neqsim.process.equipment.util.MultiVariableAdjuster
All Implemented Interfaces:
Serializable, Runnable, ProcessEquipmentInterface, ProcessElementInterface, SimulationInterface, NamedInterface
public class MultiVariableAdjuster extends ProcessEquipmentBaseClass
Multi-variable adjuster for simultaneous convergence of coupled process specifications.

This class solves the multi-variable analog of the single-variable Adjuster: given N manipulated (adjusted) variables and N target specifications, it simultaneously drives all targets to their desired values using damped successive substitution.

The underlying algorithm uses damped successive substitution (x_{n+1} = x_n + alpha * residuals) which provides robust first-order convergence for a wide range of process gains.

Problem Statement

Given N adjusted variables x_1, ..., x_N and N target specifications y_1, ..., y_N with target values t_1, ..., t_N, find the values of x that satisfy: 

f_i(x) = y_i(x) - t_i = 0   for i = 1, ..., N

Key Features

  • Simultaneous N-variable convergence (vs N independent single-variable loops)
  • Damped successive substitution with configurable relaxation
  • Variable bounds enforcement with clamping
  • Configurable convergence tolerance and maximum iterations
  • Support for pressure, temperature, flow rate, and molar flow adjustments

Usage Example

MultiVariableAdjuster adj = new MultiVariableAdjuster("MV-Adj");

// Add adjusted variables (manipulated)
adj.addAdjustedVariable(compressor, "pressure", "bara");
adj.addAdjustedVariable(heater, "temperature", "C");

// Add target specifications (in same order)
adj.addTargetSpecification(separator, "pressure", 85.0, "bara");
adj.addTargetSpecification(cooler, "temperature", 30.0, "C");

// Optional: set bounds
adj.setVariableBounds(0, 50.0, 200.0); // pressure
adj.setVariableBounds(1, 10.0, 100.0); // temperature

// Add to process system and run
process.add(adj);
process.run();
Version:
1.0
Author:
NeqSim
See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serialization version UID.
      See Also:

    • logger

      private static final org.apache.logging.log4j.Logger logger
      Logger object for class.

    • adjustedVariables

      private List<MultiVariableAdjuster.AdjustedVariable> adjustedVariables
      List of adjusted (manipulated) variable definitions.

    • targetSpecifications

      private List<MultiVariableAdjuster.TargetSpecification> targetSpecifications
      List of target specification definitions.

    • maxIterations

      private int maxIterations
      Maximum number of outer iterations.

    • tolerance

      private double tolerance
      Convergence tolerance on the residual norm.

    • iterations

      private int iterations
      Current iteration count.

    • maxResidual

      private double maxResidual
      Current maximum residual.

    • converged

      private boolean converged
      Whether the adjuster has converged.

  • Constructor Details

    • MultiVariableAdjuster

      public MultiVariableAdjuster()
      Default constructor for MultiVariableAdjuster.

    • MultiVariableAdjuster

      public MultiVariableAdjuster(String name)
      Constructor with name.
      Parameters:
      name - equipment name

  • Method Details

    • addAdjustedVariable

      public void addAdjustedVariable(ProcessEquipmentInterface equipment, String variable, String unit)
      Add an adjusted (manipulated) variable.
      Parameters:
      equipment - the equipment whose variable is manipulated
      variable - the variable name (pressure, temperature, flow)
      unit - the unit string (bara, C, kg/hr, etc.)

    • addTargetSpecification

      public void addTargetSpecification(ProcessEquipmentInterface equipment, String variable, double targetValue, String unit)
      Add a target specification.
      Parameters:
      equipment - the equipment whose variable is observed
      variable - the variable name (pressure, temperature, flow, volume)
      targetValue - the desired target value
      unit - the unit string

    • addTargetSpecification

      public void addTargetSpecification(ProcessEquipmentInterface equipment, String variable, double targetValue, String unit, String phase, String component)
      Add a target specification with phase and component.
      Parameters:
      equipment - the equipment whose variable is observed
      variable - the variable name
      targetValue - the desired target value
      unit - the unit string
      phase - the phase name (gas, oil, aqueous)
      component - the component name

    • setVariableBounds

      public void setVariableBounds(int index, double lower, double upper)
      Set bounds on an adjusted variable.
      Parameters:
      index - zero-based index of the adjusted variable
      lower - lower bound
      upper - upper bound

    • setMaxIterations

      public void setMaxIterations(int maxIter)
      Set maximum number of iterations.
      Parameters:
      maxIter - maximum iterations

    • setTolerance

      public void setTolerance(double tol)
      Set convergence tolerance.
      Parameters:
      tol - convergence tolerance on max residual

    • getIterations

      public int getIterations()
      Get the number of iterations performed in the last run.
      Returns:
      iteration count

    • getMaxResidual

      public double getMaxResidual()
      Get the maximum residual from the last run.
      Returns:
      maximum residual value

    • isConverged

      public boolean isConverged()
      Check if the adjuster converged in the last run.
      Returns:
      true if converged

    • getNumberOfVariables

      public int getNumberOfVariables()
      Get the number of adjusted variables.
      Returns:
      number of adjusted variables

    • run

      public void run(UUID id)
      Run one step of the multi-variable adjustment.

      Unlike an internal iteration loop, this method performs a single damped step per call. The ProcessSystem provides the outer iteration loop: it runs all equipment, calls this method, checks solved(), and re-runs the process if needed. This ensures downstream equipment is re-evaluated between adjustment steps.

      Parameters:
      id - calculation identifier for tracking

    • computeResiduals

      private double[] computeResiduals()
      Compute the residual vector (target - current) for all specifications.
      Returns:
      array of residuals

    • readAdjustedValue

      private double readAdjustedValue(int index)
      Read the current value of an adjusted variable from its equipment.
      Parameters:
      index - index of the adjusted variable
      Returns:
      current value in the specified unit

    • writeAdjustedValue

      private void writeAdjustedValue(int index, double value)
      Write a new value to an adjusted variable's equipment.
      Parameters:
      index - index of the adjusted variable
      value - new value to set

    • readTargetValue

      private double readTargetValue(MultiVariableAdjuster.TargetSpecification ts)
      Read the current value of a target specification from its equipment.
      Parameters:
      ts - target specification
      Returns:
      current value in the specified unit

    • getStreamFromEquipment

      private StreamInterface getStreamFromEquipment(ProcessEquipmentInterface equipment)
      Get a stream interface from equipment, handling various equipment types.
      Parameters:
      equipment - the equipment to get the stream from
      Returns:
      stream interface, or null if not available

    • maxAbsValue

      private double maxAbsValue(double[] arr)
      Compute the maximum absolute value in an array.
      Parameters:
      arr - the array
      Returns:
      maximum absolute value

    • solved

      public boolean solved()
      Check if the adjuster is solved (converged).
      Specified by:
      solved in interface SimulationInterface
      Overrides:
      solved in class ProcessEquipmentBaseClass
      Returns:
      true if the maximum residual is within tolerance