Class ProcessSimulationEvaluator

java.lang.Object
neqsim.process.util.optimizer.ProcessSimulationEvaluator
All Implemented Interfaces:
Serializable
public class ProcessSimulationEvaluator extends Object implements Serializable
Black-box evaluator for external optimization algorithms.

This class provides a unified interface for using NeqSim process simulations with external optimization libraries such as SciPy, NLopt, Pyomo, or any gradient-based/derivative-free optimizer.

Key Features

  • Single-point evaluation: evaluate(double[] x) runs simulation and returns all outputs
  • Parameter definition with bounds for decision variables
  • Multiple objectives support for multi-objective optimization
  • Constraint handling with automatic feasibility checking
  • Gradient estimation via finite differences for gradient-based optimizers
  • Thread-safe evaluation with process cloning option

Python Integration Example 

# Using with SciPy
from neqsim import jneqsim
from scipy.optimize import minimize

# Setup evaluator
evaluator = jneqsim.process.util.optimizer.ProcessSimulationEvaluator(process)
evaluator.addParameter("feed", "flowRate", 1000.0, 100000.0, "kg/hr")
evaluator.addObjective("power", lambda p: p.getUnit("Compressor").getPower("kW"))
evaluator.addConstraint("surge", lambda p: p.getUnit("Compressor").getSurgeMargin(), 0.1, 1.0)

# Optimize
def objective(x):
    result = evaluator.evaluate(x)
    return result.getObjectives()[0]

def constraint(x):
    result = evaluator.evaluate(x)
    return result.getConstraintMargins()

result = minimize(objective, x0=[50000], bounds=evaluator.getBoundsAsList(),
                  constraints={'type': 'ineq', 'fun': constraint})
Version:
1.0
Author:
NeqSim Development Team
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.

    • processSystem

      private ProcessSystem processSystem
      The process system to evaluate.

    • parameters

      private List<ProcessSimulationEvaluator.ParameterDefinition> parameters
      List of parameter definitions.

    • objectives

      private List<ProcessSimulationEvaluator.ObjectiveDefinition> objectives
      List of objective functions.

    • constraints

      private List<ProcessSimulationEvaluator.ConstraintDefinition> constraints
      List of constraints.

    • finiteDifferenceStep

      private double finiteDifferenceStep
      Step size for finite difference gradient estimation.

    • useRelativeStep

      private boolean useRelativeStep
      Whether to use relative step size for finite differences.

    • cloneForEvaluation

      private boolean cloneForEvaluation
      Whether to clone process for each evaluation (thread-safe but slower).

    • evaluationCount

      private int evaluationCount
      Counter for number of evaluations.

    • lastResult

      private transient ProcessSimulationEvaluator.EvaluationResult lastResult
      Last evaluation result for caching.

    • lastParameters

      private double[] lastParameters
      Last parameter values for cache validation.

  • Constructor Details

    • ProcessSimulationEvaluator

      public ProcessSimulationEvaluator()
      Default constructor.

    • ProcessSimulationEvaluator

      public ProcessSimulationEvaluator(ProcessSystem processSystem)
      Constructor with process system.
      Parameters:
      processSystem - the process system to evaluate

  • Method Details

    • addParameter

      public ProcessSimulationEvaluator addParameter(String equipmentName, String propertyName, double lowerBound, double upperBound, String unit)
      Adds a parameter (decision variable) for optimization.
      Parameters:
      equipmentName - name of the equipment
      propertyName - property to vary (flowRate, pressure, temperature, etc.)
      lowerBound - lower bound
      upperBound - upper bound
      unit - unit of measurement
      Returns:
      this evaluator for chaining

    • addParameterWithSetter

      public ProcessSimulationEvaluator addParameterWithSetter(String name, BiConsumer<ProcessSystem, Double> setter, double lowerBound, double upperBound, String unit)
      Adds a parameter with a custom setter function.
      Parameters:
      name - parameter name
      setter - function to set the parameter value
      lowerBound - lower bound
      upperBound - upper bound
      unit - unit of measurement
      Returns:
      this evaluator for chaining

    • getParameters

      public List<ProcessSimulationEvaluator.ParameterDefinition> getParameters()
      Gets all parameter definitions.
      Returns:
      list of parameters

    • getParameterCount

      public int getParameterCount()
      Gets number of parameters.
      Returns:
      parameter count

    • getBounds

      public double[][] getBounds()
      Gets parameter bounds as 2D array [[lb1,ub1], [lb2,ub2], ...].
      Returns:
      bounds array

    • getLowerBounds

      public double[] getLowerBounds()
      Gets lower bounds array.
      Returns:
      lower bounds

    • getUpperBounds

      public double[] getUpperBounds()
      Gets upper bounds array.
      Returns:
      upper bounds

    • getInitialValues

      public double[] getInitialValues()
      Gets initial values array.
      Returns:
      initial values

    • addObjective

      public ProcessSimulationEvaluator addObjective(String name, ToDoubleFunction<ProcessSystem> evaluator)
      Adds an objective function to minimize.
      Parameters:
      name - objective name
      evaluator - function that evaluates the objective
      Returns:
      this evaluator for chaining

    • addObjective

      public ProcessSimulationEvaluator addObjective(String name, ToDoubleFunction<ProcessSystem> evaluator, ProcessSimulationEvaluator.ObjectiveDefinition.Direction direction)
      Adds an objective function with direction.
      Parameters:
      name - objective name
      evaluator - function that evaluates the objective
      direction - MINIMIZE or MAXIMIZE
      Returns:
      this evaluator for chaining

    • addObjective

      public ProcessSimulationEvaluator addObjective(String name, ToDoubleFunction<ProcessSystem> evaluator, ProcessSimulationEvaluator.ObjectiveDefinition.Direction direction, double weight)
      Adds a weighted objective function.
      Parameters:
      name - objective name
      evaluator - function that evaluates the objective
      direction - MINIMIZE or MAXIMIZE
      weight - weight for multi-objective optimization
      Returns:
      this evaluator for chaining

    • getObjectives

      public List<ProcessSimulationEvaluator.ObjectiveDefinition> getObjectives()
      Gets all objective definitions.
      Returns:
      list of objectives

    • getObjectiveCount

      public int getObjectiveCount()
      Gets number of objectives.
      Returns:
      objective count

    • addConstraintLowerBound

      public ProcessSimulationEvaluator addConstraintLowerBound(String name, ToDoubleFunction<ProcessSystem> evaluator, double lowerBound)
      Adds a constraint: g(x) >= lowerBound.
      Parameters:
      name - constraint name
      evaluator - function that evaluates g(x)
      lowerBound - minimum allowed value
      Returns:
      this evaluator for chaining

    • addConstraintUpperBound

      public ProcessSimulationEvaluator addConstraintUpperBound(String name, ToDoubleFunction<ProcessSystem> evaluator, double upperBound)
      Adds a constraint: g(x) <= upperBound.
      Parameters:
      name - constraint name
      evaluator - function that evaluates g(x)
      upperBound - maximum allowed value
      Returns:
      this evaluator for chaining

    • addConstraintRange

      public ProcessSimulationEvaluator addConstraintRange(String name, ToDoubleFunction<ProcessSystem> evaluator, double lowerBound, double upperBound)
      Adds a range constraint: lowerBound <= g(x) <= upperBound.
      Parameters:
      name - constraint name
      evaluator - function that evaluates g(x)
      lowerBound - minimum value
      upperBound - maximum value
      Returns:
      this evaluator for chaining

    • addConstraintEquality

      public ProcessSimulationEvaluator addConstraintEquality(String name, ToDoubleFunction<ProcessSystem> evaluator, double target, double tolerance)
      Adds an equality constraint: g(x) == target (within tolerance).
      Parameters:
      name - constraint name
      evaluator - function that evaluates g(x)
      target - target value
      tolerance - allowed deviation
      Returns:
      this evaluator for chaining

    • getConstraints

      public List<ProcessSimulationEvaluator.ConstraintDefinition> getConstraints()
      Gets all constraint definitions.
      Returns:
      list of constraints

    • getConstraintCount

      public int getConstraintCount()
      Gets number of constraints.
      Returns:
      constraint count

    • addEquipmentCapacityConstraints

      public ProcessSimulationEvaluator addEquipmentCapacityConstraints()
      Auto-discovers equipment capacity constraints and adds them as constraint definitions.

      Uses the EquipmentCapacityStrategyRegistry to find all physical limits across every equipment item in the process (compressor surge, separator flooding, pipe velocity, etc.) and converts each to an upper-bound ProcessSimulationEvaluator.ConstraintDefinition where g(x) = utilization <= 1.0.

      This ensures external optimizers get exactly the same physical constraints that internal NeqSim optimizers discover automatically, without manual re-creation.

      Returns:
      this evaluator for chaining

    • getAllProcessConstraints

      public List<ProcessConstraint> getAllProcessConstraints()
      Returns all constraints as a unified ProcessConstraint list.

      Since ProcessSimulationEvaluator.ConstraintDefinition implements ProcessConstraint, this returns the same constraints in their unified form — usable by both internal and external optimizers.

      Returns:
      list of all constraints as ProcessConstraint instances

    • getConstraintMarginVector

      public double[] getConstraintMarginVector(ProcessSystem process)
      Evaluates all constraints and returns a margin vector suitable for NLP solvers.

      Each element is a constraint margin: positive means satisfied, negative means violated. This is the g(x) >= 0 vector expected by standard NLP libraries.

      Parameters:
      process - the process system (must have been run)
      Returns:
      array of constraint margins in registration order

    • evaluate

      public ProcessSimulationEvaluator.EvaluationResult evaluate(double[] x)
      Evaluates the process for given parameter values.

      This is the main entry point for external optimizers. It:

      1. Sets all parameter values on the process
      2. Runs the simulation
      3. Evaluates all objectives and constraints
      4. Returns a complete result object
      Parameters:
      x - array of parameter values (length must match parameter count)
      Returns:
      evaluation result with objectives, constraints, and feasibility

    • setParameterValues

      private void setParameterValues(ProcessSystem process, double[] x)
      Sets parameter values on the process.
      Parameters:
      process - the process system
      x - parameter values

    • setEquipmentProperty

      private void setEquipmentProperty(ProcessSystem process, String equipmentName, String propertyName, double value, String unit)
      Sets a property on equipment by name.
      Parameters:
      process - the process system
      equipmentName - equipment name
      propertyName - property name
      value - value to set
      unit - unit of measurement

    • estimateGradient

      public double[] estimateGradient(double[] x)
      Estimates the gradient of the primary objective using finite differences.
      Parameters:
      x - parameter values
      Returns:
      gradient array

    • estimateGradient

      public double[] estimateGradient(double[] x, int objectiveIndex)
      Estimates the gradient of a specific objective using finite differences.
      Parameters:
      x - parameter values
      objectiveIndex - which objective (0-based)
      Returns:
      gradient array

    • estimateConstraintJacobian

      public double[][] estimateConstraintJacobian(double[] x)
      Estimates the Jacobian of all constraints using finite differences.
      Parameters:
      x - parameter values
      Returns:
      Jacobian matrix [constraints x parameters]

    • evaluateObjective

      public double evaluateObjective(double[] x)
      Evaluates just the primary objective (for simple scalar optimizers).
      Parameters:
      x - parameter values
      Returns:
      objective value (for minimization)

    • evaluatePenalizedObjective

      public double evaluatePenalizedObjective(double[] x)
      Evaluates the penalized objective (objective + constraint penalties).
      Parameters:
      x - parameter values
      Returns:
      penalized objective

    • isFeasible

      public boolean isFeasible(double[] x)
      Checks if a point is feasible.
      Parameters:
      x - parameter values
      Returns:
      true if all constraints satisfied

    • getConstraintMargins

      public double[] getConstraintMargins(double[] x)
      Gets constraint margins (positive = satisfied).
      Parameters:
      x - parameter values
      Returns:
      array of constraint margins

    • getProcessSystem

      public ProcessSystem getProcessSystem()

    • setProcessSystem

      public void setProcessSystem(ProcessSystem processSystem)

    • getFiniteDifferenceStep

      public double getFiniteDifferenceStep()

    • setFiniteDifferenceStep

      public void setFiniteDifferenceStep(double finiteDifferenceStep)

    • isUseRelativeStep

      public boolean isUseRelativeStep()

    • setUseRelativeStep

      public void setUseRelativeStep(boolean useRelativeStep)

    • isCloneForEvaluation

      public boolean isCloneForEvaluation()

    • setCloneForEvaluation

      public void setCloneForEvaluation(boolean cloneForEvaluation)

    • getEvaluationCount

      public int getEvaluationCount()

    • resetEvaluationCount

      public void resetEvaluationCount()

    • getLastResult

      public ProcessSimulationEvaluator.EvaluationResult getLastResult()

    • getProblemDefinition

      public Map<String,Object> getProblemDefinition()
      Gets problem definition as a map (for JSON export).
      Returns:
      map representation of the problem

    • toJson

      public String toJson()
      Gets problem definition as JSON string.
      Returns:
      JSON representation