Scaling

This section describes scaling utility functions and methods.

Standard Practice

Scaling factors can be specified for any variable or constraint. Pyomo and many solvers support the scaling_factor suffix. IDAES, as described below, also supports the scaling_expression suffix which can be used to calculate scaling_factor values (e.g. based on state block units of measure).

To eliminate the possibility of defining, conflicting scaling factors in various places in the model the IDAES standard is to define the scaling_factor and scaling_expression suffixes in the same block as the variable or constraint that they are scaling. This ensures that each scale factor is defined in only one place, and is organized based on the model block structure.

Scaling factors in IDAES (and Pyomo) are multiplied by the variable or constraint they scale. For example, a Pressure variable in Pa units may be expected to have a magnitude of around \(1\times10^6\) for a specific process. To scale the variable to a more reasonable magnitude the scale factor for the variable could be defined to be \(1\times10^-5\).

Specifying Variable Scaling

Suffixes are used to specify scaling factors for IDAES models. Some solvers, such as Ipopt, support supplying scale factors. Pyomo also supplies scaling transformations for models when solver scaling is not supported.

To supply variable and constraint scaling factors, a suffix called scaling_factor should be created in the same block as the variable or constraint. For example:

from pyomo.environ import Suffix, ConcreteModel, Var

m = ConcreteModel()
m.scaling_factor = Suffix(direction=Suffix.EXPORT)
m.P = Var(initialize=1e6, doc="Pressure [Pa]")
m.conc = Var(["Na+", "Cl-"], initialize=1e-4)
m.scaling_factor[m.P] = 1e-5
m.scaling_factor[m.conc["Na+"]] = 1e3
m.scaling_factor[m.conc["Cl-"]] = 1e3

Variable scaling in state blocks is provided by the developer of a state block and can be used as a basis for scaling other model variables and constraints. Scaling factors can be modified by users to better represent the process they are modeling.

Specifying Scaling Factor Expressions

Scaling factors for variables and constraints can be calculated based on variable scaling factors, bounds, or values that have been provided. The calculation for a scaling factor can be provided as a python expression using model variables in the scaling_expression suffix. For variables, generally the expression should only depend on variables where scaling factors have been defined.

The calculate_scaling_factors(m, basis) function replaces the variables in the scaling expression with the specified basis values, calculates the scaling factors, and puts the scaling factor in the scaling_factor suffix.

from pyomo.environ import Suffix, ConcreteModel, Var, Constraint
from idaes.core.util.scaling import (
    ScalingBasis,
    calculate_scaling_factors,
)

m = ConcreteModel()
m.scaling_factor = Suffix(direction=Suffix.EXPORT)
m.scaling_expression = Suffix(direction=Suffix.LOCAL)

m.x = Var(initialize=1e6)
m.y = Var(initialize=1e6)
m.z = Var(initialize=1e12)

m.scaling_factor[m.x] = 1e-5
m.scaling_factor[m.y] = 1e-5
m.scaling_expression[m.z] = 1/(m.x*m.y)

m.c = Constraint(expr=m.z == m.x*m.y)
m.scaling_expression[m.c] = 1/(m.x*m.y)

calculate_scaling_factors(m, basis=ScalingBasis.InverseVarScale)

# Show that the constraint scaling factor is 1/((1/1e-5)*(1/1e-5))
assert(m.scaling_factor[m.c] - 1e-10 < 1e-12)
# Show that the z variable scaling factor is 1/((1/1e-5)*(1/1e-5))
assert(m.scaling_factor[m.z] - 1e-10 < 1e-12)

In the scaling expression the general guideline is that a scaling factor is being calculated based on the expected magnitude of the variable values. The magnitude could be estimated in different ways, but the most common way should be the inverse variable scale. The list below shows variable scaling bases that are provided.

ScalingBasis.InverseVarScale:
Use the inverse variable scaling factors in scaling expressions.
ScalingBasis.Value:
Use the current variable values in scaling expressions.
ScalingBasis.Mid:
Use the mid-point between the upper and lower bounds in scaling expressions.
ScalingBasis.Lower:
Use the lower bound of variables in scaling expressions.
ScalingBasis.Upper:
Use the lower bound of variables in scaling expressions.
ScalingBasis.VarScale:
This is less common, but it uses the variable scales directly. This can be used if you are using alternative scaling methods with divide by the scaling factor.
idaes.core.util.scaling.calculate_scaling_factors(m, basis=(<ScalingBasis.InverseVarScale: 3>, <ScalingBasis.Mid: 6>, <ScalingBasis.Value: 1>))[source]

Set scale factors for variables and constraints from expressions stored in the scaling_expression suffix. The variables and Expressions in the scaling expressions are replaced by the scaling basis values before calculating the scaling factor. Variable scale factors are calculated first, and variable scaling expressions should be based on variables whose scale factors are supplied directly. Constraint scaling expressions can be based on any variables.

Parameters:
  • m (Block) – A Pyomo model or block to apply the scaling expressions to.
  • basis – (ScalingBasis or List-like of ScalingBasis): Value to use when evaluating scaling expressions. A list-like of ScalingBasis can be used to provide fall-back values in the event that the first choice is not available. If none of the bases are available, 1 is used.
Returns:

None

Scaling Utility Functions

IDAES includes some utility functions to help evaluate model scaling and to auto-scale constraints.

idaes.core.util.scaling.badly_scaled_var_generator(blk, large=10000.0, small=0.001, zero=1e-10)[source]

This provides a rough check for variables with poor scaling based on their current scale factors and values. For each potentially poorly scaled variable it returns the var and its current scaled value.

Parameters:
  • large – Magnitude that is considered to be too large
  • small – Magnitude that is considered to be too small
  • zero – Magnitude that is considered to be zero, variables with a value of zero are okay, and not reported.
Yields:

variable data object, current absolute value of scaled value
idaes.core.util.scaling.grad_fd(c, scaled=False, h=1e-06)[source]

Finite difference the gradient for a constraint, objective or named expression. This is only for use in examining scaling. For faster more accurate gradients refer to pynumero.

Parameters:
  • c – constraint to evaluate
  • scaled – if True calculate the scaled grad (default=False)
  • h – step size for calculating finite differnced derivatives
Returns:

(list of gradient values, list for varibles in the constraint) The order

of the variables coresoponds to the gradient values.
idaes.core.util.scaling.scale_constraint(c, v=None)[source]

This transforms a constraint with its scaling factor or a given scaling factor value. If it uses the scaling factor suffix value, the scaling factor suffix is set to 1 to avoid double scaling the constraint. This can be used when to scale constraints before sending the model to the solver.

Parameters:
  • c – Pyomo constraint
  • v – Scale factor. If None, use value from scaling factor suffix and set suffix value to 1.
Returns:

None
idaes.core.util.scaling.constraint_fd_autoscale(c, min_scale=1e-06, max_grad=100)[source]

Autoscale constraints so that if there maximum partial derivative with respect to any variable is greater than max_grad at the current variable values, the method will attempt to assign a scaling factor to the constraint that makes the maximum derivative max_grad. The min_scale value provides a lower limit allowed for constraint scaling factors. If the caclulated scaling factor to make the maxium derivative max_grad is less than min_scale, min_scale is used instead. Derivatives are approximated using finite differnce.

Parameters:
  • c – constraint object
  • max_grad – the largest derivative after scaling subject to min_scale
  • min_scale – the minimum scale factor allowed
Returns:

None
idaes.core.util.scaling.set_scaling_factor(c, v)[source]

Set a scaling factor for a model component. This function creates the scaling_factor suffix if needed.

Parameters:
  • c – component to supply scaling factor for
  • v – scaling factor
Returns:

None

Scaling with Ipopt

To use the supplied scaling factors with Ipopt the nlp_scaling_method solver option should be set to “user-scaling.”