Class CapacityConstraint

java.lang.Object
neqsim.process.equipment.capacity.CapacityConstraint
All Implemented Interfaces:
Serializable
public class CapacityConstraint extends Object implements Serializable
Represents a capacity constraint for process equipment.

A capacity constraint defines a limit on equipment operation, such as maximum speed, flow rate, or load factor. It tracks the current value, design value, and maximum allowable value, and calculates utilization as a percentage of design capacity.

Example usage: 

CapacityConstraint speedConstraint = new CapacityConstraint("speed", "RPM", ConstraintType.HARD)
    .setDesignValue(10000.0).setMaxValue(11000.0).setWarningThreshold(0.9)
    .setValueSupplier(() -> compressor.getSpeed());
Version:
1.0
Author:
NeqSim Development Team
See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serialization version.
      See Also:

    • MAX_UTILIZATION

      private static final double MAX_UTILIZATION
      Maximum utilization value returned by getUtilization(). Caps extreme values (e.g., when design value is near zero or current value is far beyond design) to prevent unbounded utilization percentages that confuse optimization and reporting.
      See Also:

    • name

      private final String name
      Name of the constraint (e.g., "speed", "gasLoadFactor").

    • unit

      private final String unit
      Unit of measurement (e.g., "RPM", "m/s", "kW").

    • unitOverride

      private String unitOverride
      Override unit for mutable unit changes.

    • type

      private final CapacityConstraint.ConstraintType type
      Type of constraint (HARD, SOFT, or DESIGN).

    • severity

      private CapacityConstraint.ConstraintSeverity severity
      Severity level for optimization (CRITICAL, HARD, SOFT, ADVISORY).

    • designValue

      private double designValue
      Design/rated value for this constraint.

    • maxValue

      private double maxValue
      Absolute maximum value (for HARD constraints).

    • minValue

      private double minValue
      Minimum required value (for constraints like residence time).

    • warningThreshold

      private double warningThreshold
      Fraction of design value that triggers a warning (e.g., 0.9 = 90%).

    • valueSupplier

      private transient DoubleSupplier valueSupplier
      Supplier function to get current value from equipment. Marked transient because lambdas/method references are not serializable. After deserialization, this will be null and the cached currentValue will be used instead.

    • currentValue

      private double currentValue
      Cached current value (updated when getCurrentValue() is called).

    • description

      private String description
      Description of the constraint for documentation.

    • enabled

      private boolean enabled
      Whether this constraint is enabled for capacity analysis.

  • Constructor Details

    • CapacityConstraint

      public CapacityConstraint(String name, String unit, CapacityConstraint.ConstraintType type)
      Creates a new capacity constraint.
      Parameters:
      name - the name of the constraint
      unit - the unit of measurement
      type - the constraint type (HARD, SOFT, or DESIGN)

    • CapacityConstraint

      public CapacityConstraint(String name)
      Creates a new capacity constraint with default type SOFT and empty unit.

      This constructor is a convenience for building constraints where the unit and type can be set later using the fluent API.

      Parameters:
      name - the name of the constraint

  • Method Details

    • setDesignValue

      public CapacityConstraint setDesignValue(double designValue)
      Sets the design/rated value for this constraint.
      Parameters:
      designValue - the design value
      Returns:
      this constraint for method chaining

    • setMaxValue

      public CapacityConstraint setMaxValue(double maxValue)
      Sets the maximum allowable value (for HARD constraints).
      Parameters:
      maxValue - the maximum value
      Returns:
      this constraint for method chaining

    • setMinValue

      public CapacityConstraint setMinValue(double minValue)
      Sets the minimum required value (for constraints like residence time).
      Parameters:
      minValue - the minimum value
      Returns:
      this constraint for method chaining

    • setWarningThreshold

      public CapacityConstraint setWarningThreshold(double warningThreshold)
      Sets the warning threshold as a fraction of design value.
      Parameters:
      warningThreshold - fraction (0.0 to 1.0) at which to warn
      Returns:
      this constraint for method chaining

    • setSeverity

      public CapacityConstraint setSeverity(CapacityConstraint.ConstraintSeverity severity)
      Sets the severity level for this constraint.

      Severity affects how the optimizer handles violations:

      • CRITICAL: Optimizer must stop immediately
      • HARD: Solution marked as infeasible
      • SOFT: Penalty applied to objective
      • ADVISORY: Information only
      Parameters:
      severity - the severity level
      Returns:
      this constraint for method chaining

    • getSeverity

      public CapacityConstraint.ConstraintSeverity getSeverity()
      Gets the severity level for this constraint.
      Returns:
      the severity level

    • isCriticalViolation

      public boolean isCriticalViolation()
      Checks if this is a critical violation that requires immediate action.

      Critical violations indicate equipment damage or safety hazard. The optimizer should stop immediately when this returns true.

      Returns:
      true if constraint is CRITICAL severity and violated

    • setValueSupplier

      public CapacityConstraint setValueSupplier(DoubleSupplier supplier)
      Sets the supplier function to get the current value from equipment.
      Parameters:
      supplier - the value supplier function
      Returns:
      this constraint for method chaining

    • setDescription

      public CapacityConstraint setDescription(String description)
      Sets a description for this constraint.
      Parameters:
      description - the description text
      Returns:
      this constraint for method chaining

    • setCurrentValue

      public CapacityConstraint setCurrentValue(double value)
      Sets the current value directly. Use this when you want to set the value manually rather than using a supplier function.

      Note: If a value supplier is set, it will override this value when getCurrentValue() is called.

      Parameters:
      value - the current value to set
      Returns:
      this constraint for method chaining

    • setUnit

      public CapacityConstraint setUnit(String unit)
      Sets the unit of measurement for this constraint.

      This is a convenience method for cases where the unit needs to be changed after construction.

      Parameters:
      unit - the unit of measurement
      Returns:
      this constraint for method chaining

    • getCurrentValue

      public double getCurrentValue()
      Gets the current value from the equipment.
      Returns:
      the current value, or 0.0 if no supplier is set

    • getUtilization

      public double getUtilization()
      Gets the utilization as a fraction of design value.

      For normal constraints (higher is worse), returns current/design. For minimum constraints (lower is worse), returns design/current.

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

    • getUtilizationPercent

      public double getUtilizationPercent()
      Gets the utilization as a percentage of design value.
      Returns:
      utilization as percentage (100.0 = 100% of design)

    • isViolated

      public boolean isViolated()
      Checks if this constraint is violated (exceeds design capacity).
      Returns:
      true if utilization exceeds 100%

    • isHardLimitExceeded

      public boolean isHardLimitExceeded()
      Checks if this constraint exceeds the absolute maximum (for HARD constraints).
      Returns:
      true if current value exceeds max value

    • isNearLimit

      public boolean isNearLimit()
      Checks if this constraint is near its limit (above warning threshold).
      Returns:
      true if utilization exceeds warning threshold

    • getMargin

      public double getMargin()
      Gets the margin to design capacity.
      Returns:
      remaining capacity as fraction (0.2 = 20% margin remaining)

    • getMarginPercent

      public double getMarginPercent()
      Gets the margin to design capacity as a percentage.
      Returns:
      remaining capacity as percentage

    • getName

      public String getName()
      Gets the constraint name.
      Returns:
      the name

    • getUnit

      public String getUnit()
      Gets the unit of measurement.
      Returns:
      the unit (or unitOverride if set)

    • getType

      public CapacityConstraint.ConstraintType getType()
      Gets the constraint type.
      Returns:
      the type

    • getDesignValue

      public double getDesignValue()
      Gets the design value.
      Returns:
      the design value

    • getDisplayDesignValue

      public double getDisplayDesignValue()
      Gets the display design value for reporting purposes. For minimum constraints (where designValue is MAX_VALUE), this returns the minValue instead.
      Returns:
      the design value for display purposes

    • isMinimumConstraint

      public boolean isMinimumConstraint()
      Checks if this is a minimum constraint (where being above the minimum is good).
      Returns:
      true if this is a minimum constraint

    • getMaxValue

      public double getMaxValue()
      Gets the maximum allowable value.
      Returns:
      the max value

    • getMinValue

      public double getMinValue()
      Gets the minimum required value.
      Returns:
      the min value

    • getWarningThreshold

      public double getWarningThreshold()
      Gets the warning threshold.
      Returns:
      the warning threshold as fraction

    • getDescription

      public String getDescription()
      Gets the description.
      Returns:
      the description

    • isEnabled

      public boolean isEnabled()
      Checks if this constraint is enabled for capacity analysis.

      Disabled constraints are excluded from bottleneck detection and optimization. They still track values but don't contribute to utilization summaries.

      Returns:
      true if the constraint is enabled

    • setEnabled

      public CapacityConstraint setEnabled(boolean enabled)
      Enables or disables this constraint for capacity analysis.

      When disabled, this constraint is excluded from:

      • Bottleneck detection
      • Capacity utilization summaries
      • Optimization constraints
      • Near-limit warnings

      The constraint still tracks its current value and can be queried directly.

      Parameters:
      enabled - true to enable, false to disable
      Returns:
      this constraint for method chaining

    • toString

      public String toString()
      Overrides:
      toString in class Object