Class ProcessSensitivityAnalyzer

java.lang.Object
neqsim.process.util.sensitivity.ProcessSensitivityAnalyzer
All Implemented Interfaces:
Serializable
public class ProcessSensitivityAnalyzer extends Object implements Serializable
Comprehensive sensitivity analyzer for process simulations.

This class provides a fluent API for computing sensitivities of any output property with respect to any input property. It intelligently leverages available Jacobians from Broyden convergence when possible, falling back to finite differences only when necessary.

Key Features:

  • Fluent API for defining input/output pairs
  • Automatic integration with Broyden convergence Jacobians (FREE sensitivities)
  • Chain rule optimization through tear stream structure
  • Direct property access for any equipment via reflection

Usage Example: 

ProcessSensitivityAnalyzer analyzer = new ProcessSensitivityAnalyzer(process);

// Define what we want to compute
analyzer.withInput("feed", "flowRate").withInput("feed", "temperature")
    .withOutput("product", "temperature").withOutput("product", "pressure");

// Compute sensitivities (uses Broyden Jacobian if available)
SensitivityMatrix result = analyzer.compute();

// Query specific sensitivity
double dT_dFlow = result.getSensitivity("product.temperature", "feed.flowRate");
Version:
1.0
Author:
ESOL
See Also:

  • Field Details

    • serialVersionUID

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

    • logger

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

    • processSystem

      private final ProcessSystem processSystem
      The process system to analyze.

    • inputSpecs

      private final List<ProcessSensitivityAnalyzer.VariableSpec> inputSpecs
      Input variable specifications.

    • outputSpecs

      private final List<ProcessSensitivityAnalyzer.VariableSpec> outputSpecs
      Output variable specifications.

    • relativePerturbation

      private double relativePerturbation
      Relative perturbation size for finite differences.

    • minimumPerturbation

      private double minimumPerturbation
      Minimum absolute perturbation.

    • useCentralDifferences

      private boolean useCentralDifferences
      Whether to use central differences (more accurate but 2x cost).

    • cachedBroydenJacobian

      private transient double[][] cachedBroydenJacobian
      Cached Broyden Jacobian from last convergence.

    • cachedTearStreamVars

      private transient List<String> cachedTearStreamVars
      Cached tear stream variable names.

  • Constructor Details

    • ProcessSensitivityAnalyzer

      public ProcessSensitivityAnalyzer(ProcessSystem processSystem)
      Creates a new sensitivity analyzer for a process system.
      Parameters:
      processSystem - the process system to analyze

  • Method Details

    • withInput

      public ProcessSensitivityAnalyzer withInput(String equipmentName, String propertyName)
      Adds an input variable for sensitivity analysis.
      Parameters:
      equipmentName - name of the equipment
      propertyName - name of the property to perturb
      Returns:
      this analyzer for chaining

    • withInput

      public ProcessSensitivityAnalyzer withInput(String equipmentName, String propertyName, String unit)
      Adds an input variable with unit specification.
      Parameters:
      equipmentName - name of the equipment
      propertyName - name of the property
      unit - unit for the property
      Returns:
      this analyzer for chaining

    • withOutput

      public ProcessSensitivityAnalyzer withOutput(String equipmentName, String propertyName)
      Adds an output variable for sensitivity analysis.
      Parameters:
      equipmentName - name of the equipment
      propertyName - name of the property to monitor
      Returns:
      this analyzer for chaining

    • withOutput

      public ProcessSensitivityAnalyzer withOutput(String equipmentName, String propertyName, String unit)
      Adds an output variable with unit specification.
      Parameters:
      equipmentName - name of the equipment
      propertyName - name of the property
      unit - unit for the property
      Returns:
      this analyzer for chaining

    • withCentralDifferences

      public ProcessSensitivityAnalyzer withCentralDifferences(boolean useCentral)
      Sets whether to use central differences (default: false).
      Parameters:
      useCentral - true for central differences (more accurate, 2x cost)
      Returns:
      this analyzer for chaining

    • withPerturbation

      public ProcessSensitivityAnalyzer withPerturbation(double relativePert)
      Sets the relative perturbation size for finite differences.
      Parameters:
      relativePert - relative perturbation (default: 0.001 = 0.1%)
      Returns:
      this analyzer for chaining

    • reset

      public ProcessSensitivityAnalyzer reset()
      Clears all input/output specifications.
      Returns:
      this analyzer for chaining

    • compute

      public SensitivityMatrix compute()
      Computes the sensitivity matrix using the most efficient available method.

      This method automatically:

      1. Checks if Broyden Jacobian is available for tear stream variables
      2. Uses chain rule to extend to non-tear variables where possible
      3. Falls back to finite differences only for variables not covered
      Returns:
      the computed sensitivity matrix

    • computeFiniteDifferencesOnly

      public SensitivityMatrix computeFiniteDifferencesOnly()
      Forces computation using only finite differences.
      Returns:
      the computed sensitivity matrix

    • loadBroydenJacobian

      private void loadBroydenJacobian()
      Loads Broyden Jacobian from RecycleController if available.

    • findRecycleController

      private RecycleController findRecycleController()
      Finds the RecycleController for this process system.
      Returns:
      the RecycleController if found, or null if no recycles exist

    • createRecycleController

      private RecycleController createRecycleController()
      Creates a RecycleController from recycles in the process.
      Returns:
      a new RecycleController initialized with process recycles, or null if none found

    • computeFromBroyden

      private void computeFromBroyden(SensitivityMatrix result, boolean[][] computed)
      Computes sensitivities directly from Broyden Jacobian.
      Parameters:
      result - the sensitivity matrix to populate
      computed - boolean matrix tracking which entries have been computed

    • computeViaChainRule

      private void computeViaChainRule(SensitivityMatrix result, boolean[][] computed)
      Computes sensitivities using chain rule through tear streams.
      Parameters:
      result - the sensitivity matrix to populate
      computed - boolean matrix tracking which entries have been computed

    • computeViaFiniteDifferences

      private void computeViaFiniteDifferences(SensitivityMatrix result, boolean[][] computed)
      Computes remaining sensitivities via finite differences.
      Parameters:
      result - the sensitivity matrix to populate
      computed - boolean matrix tracking which entries have been computed

    • computePerturbation

      private double computePerturbation(double baseValue)

    • getPropertyValue

      private double getPropertyValue(ProcessSensitivityAnalyzer.VariableSpec spec)
      Gets a property value from equipment using reflection.
      Parameters:
      spec - the variable specification
      Returns:
      the property value

    • setPropertyValue

      private void setPropertyValue(ProcessSensitivityAnalyzer.VariableSpec spec, double value)
      Sets a property value on equipment using reflection.
      Parameters:
      spec - the variable specification
      value - the value to set

    • findEquipment

      private ProcessEquipmentInterface findEquipment(String name)
      Finds equipment by name in the process system.
      Parameters:
      name - the equipment name to search for
      Returns:
      the equipment interface, or null if not found

    • getPropertyFromEquipment

      private double getPropertyFromEquipment(ProcessEquipmentInterface equipment, String property, String unit)
      Gets a property value from equipment using reflection.
      Parameters:
      equipment - the process equipment to read from
      property - the property name
      unit - the unit string, or null
      Returns:
      the property value, or NaN if not found

    • getStandardProperty

      private double getStandardProperty(ProcessEquipmentInterface equipment, String property, String unit)
      Gets standard properties that are common across equipment types.
      Parameters:
      equipment - the process equipment to read from
      property - the property name (e.g., temperature, pressure, flowrate)
      unit - the unit string, or null for default units
      Returns:
      the property value, or NaN if not found

    • callMethodWithOptionalUnit

      private double callMethodWithOptionalUnit(ProcessEquipmentInterface equipment, String methodName, String unit, String defaultUnit) throws Exception
      Calls a method with optional unit parameter.
      Parameters:
      equipment - the process equipment to call the method on
      methodName - the name of the method to invoke
      unit - the unit string to pass, or null to use default
      defaultUnit - the default unit if unit is null
      Returns:
      the result of the method call as a double
      Throws:
      Exception - if the method invocation fails

    • setPropertyOnEquipment

      private void setPropertyOnEquipment(ProcessEquipmentInterface equipment, String property, double value, String unit)
      Sets a property value on equipment using reflection.
      Parameters:
      equipment - the process equipment to set the property on
      property - the property name to set
      value - the value to set
      unit - the unit string for the value, or null

    • setStandardProperty

      private void setStandardProperty(ProcessEquipmentInterface equipment, String property, double value, String unit)
      Sets standard properties common across equipment types.

    • callSetterWithOptionalUnit

      private void callSetterWithOptionalUnit(ProcessEquipmentInterface equipment, String methodName, double value, String unit, String defaultUnit) throws Exception
      Calls a setter with optional unit parameter.
      Throws:
      Exception

    • findMethod

      private Method findMethod(Class<?> clazz, String name, Class<?>... paramTypes)
      Finds a method on a class, searching up the hierarchy.

    • generateReport

      public String generateReport(SensitivityMatrix matrix)
      Generates a human-readable report of the sensitivity analysis.
      Parameters:
      matrix - the computed sensitivity matrix
      Returns:
      formatted report string

    • truncate

      private String truncate(String s, int maxLen)