Scaling Utility Functions

Scaling Utility Functions#

Utility functions for scaling.

Authors: Andrew Lee, Douglas Allan

idaes.core.scaling.util.del_scaling_factor(component, delete_empty_suffix=False)[source]#

Delete scaling factor for component.

Parameters:

  • component – component to delete scaling factor for

  • delete_empty_suffix (bool) – (bool) whether to delete scaling Suffix if it is empty after deletion.

idaes.core.scaling.util.get_component_scaling_suffix(component)[source]#

Get scaling suffix appropriate to component type from parent block.

Creates a new suffix if one is not found.

Parameters:

component – component to get suffix for

Returns:

Pyomo scaling factor Suffix (for VarData and ConstraintData) or Pyomo scaling hint Suffix (for ExpressionData)

Raises:

TypeError if component isn't a VarData, ConstraintData, or ExpressionData. –

idaes.core.scaling.util.get_jacobian(m, include_scaling_factors=True, include_ipopt_autoscaling=False, equality_constraints_only=False, max_grad=100, min_scale=1e-08)[source]#

Get the Jacobian matrix at the current model values. This function also returns the Pynumero NLP which can be used to identify the constraints and variables corresponding to the rows and columns.

Parameters:

  • m – model to get Jacobian from

  • include_scaling_factors – if True scale the rows and columns of the Jacobian using the user-defined scaling factors in the scaling_factor suffix.

  • include_ipopt_autoscaling – if True, include the gradient-based autoscaling step that IPOPT uses to scale the rows of the Jacobian

  • equality_constraints_only – Option to include only equality constraints in the calculated Jacobian.

  • max_grad – The value of the norm of the constraint gradient above which gradient-based autoscaling will be performed by IPOPT. This option corresponds to the IPOPT option nlp_scaling_max_gradient. Used only if include_ipopt_autoscaling is True.

  • min_scale – The smallest scaling factor that IPOPT gradient-based scaling is allowed to produce. This option corresponds to the IPOPT option nlp_scaling_min_value. Used only if include_ipopt_autoscaling is True.

Returns:

Jacobian matrix in Scipy CSR format, Pynumero nlp

idaes.core.scaling.util.get_nominal_value(component)[source]#

Get the signed nominal value for a VarData or ParamData component.

For Params, the current value of the component will be returned.

For Vars, the nominal value is determined using the assigned scaling factor and the sign determined based on the bounds and domain of the variable (defaulting to positive). If no scaling factor is set, then the current value will be used if set, otherwise the absolute nominal value will be equal to 1.

Parameters:

component – component to determine nominal value for

Returns:

signed float with nominal value

Raises:

TypeError if component is not instance of VarData or ParamData –

idaes.core.scaling.util.get_scaling_factor(component, default=None, warning=False)[source]#

Get scaling factor for component.

Parameters:

  • component – component to get scaling factor for

  • default (float) – scaling factor to return if no scaling factor exists for component

  • warning (bool) – Bool to determine whether a warning should be returned if no scaling factor is found

Returns:

float scaling factor

Raises:

TypeError if component is not VarData, ConstraintData, or ExpressionData –

idaes.core.scaling.util.get_scaling_factor_suffix(blk)[source]#

Get scaling suffix from block.

Parameters:

blk (BlockData) – component to get scaling factor suffix for

Returns:

Pyomo scaling Suffix

Raises:

TypeError if component is an IndexedBlock –

idaes.core.scaling.util.get_scaling_hint_suffix(blk)[source]#

Get scaling hint suffix from block.

Creates a new suffix if one is not found.

Parameters:

blk (BlockData) – block to get suffix for

Returns:

Pyomo scaling hint Suffix

Raises:

TypeError if component is an IndexedBlock or non-block. –

idaes.core.scaling.util.jacobian_cond(m=None, scaled=True, jac=None)[source]#

Get the Frobenius condition number of the scaled or unscaled Jacobian matrix of a model.

Parameters:

  • m – calculate the condition number of the Jacobian from this model.

  • scaled – if True use scaled Jacobian, else use unscaled

  • jac – (optional) previously calculated Jacobian

Returns:

(float) Condition number

idaes.core.scaling.util.list_unscaled_constraints(blk, descend_into=True)[source]#

Return a list of constraints which do not have a scaling factor assigned :param blk: block to check for unscaled constraints :param descend_into: bool indicating whether to check constraints in sub-blocks

Returns:

list of unscaled constraint data objects

Parameters:
idaes.core.scaling.util.list_unscaled_variables(blk, descend_into=True, include_fixed=False)[source]#

Return a list of variables which do not have a scaling factor assigned :param blk: block to check for unscaled variables :param descend_into: bool indicating whether to check variables in sub-blocks :param include_fixed: bool indicating whether to include fixed Vars in list

Returns:

list of unscaled variable data objects

Parameters:
idaes.core.scaling.util.report_scaling_factors(blk, ctype=None, descend_into=False, stream=None)[source]#

Write the scaling factors for all components in a Block to a stream.

Parameters:

  • blk (Block) – Block to get scaling factors and/or scaling hints from.

  • ctype – None, Var, Constraint, or Expression. Type of component to show scaling factors for (if None, shows all elements).

  • descend_into (bool) – whether to show scaling factors for components in sub-blocks.

  • stream – StringIO object to write results to. If not provided, writes to stdout.

Raises:

  • TypeError if blk is not a Pyomo Block. –

  • ValueError is ctype is not None, Var or Constraint. –

idaes.core.scaling.util.scale_time_discretization_equations(blk, time_set, time_scaling_factor)[source]#

Scales time discretization equations generated via a Pyomo discretization transformation. Also scales continuity equations for collocation methods of discretization that require them.

Parameters:

  • blk – Block whose time discretization equations are being scaled

  • time_set – Time set object. For an IDAES flowsheet object fs, this is fs.time.

  • time_scaling_factor – Scaling factor to use for time

Returns:

None

idaes.core.scaling.util.scaling_factors_from_dict(blk_or_suffix, json_dict, overwrite=False, verify_names=True)[source]#

Set scaling factors and/or scaling hints based on values in a serializable json dict.

This method expects components to be referenced by their local names.

Parameters:

  • blk_or_suffix – Pyomo Block or Suffix object to set scaling factors on

  • json_dict (dict) – dict of scaling factors and/or scaling hints to load into model

  • overwrite (bool) – (bool) whether to overwrite existing scaling factors/hints or not

  • verify_names (bool) – (bool) whether to verify that all names in dict exist on block

Returns

None

Raises:

TypeError if blk_or_suffix is not an instance of Block or Suffix –

Parameters:
idaes.core.scaling.util.scaling_factors_from_json_file(blk_or_suffix, filename, overwrite=False, verify_names=True)[source]#

Load scaling factors from json file.

Parameters:

  • blk_of_suffix – Block or Suffix to load scaling factors for

  • filename (str) – name of file to load as string

  • overwrite (bool) – (bool) whether to overwrite existing scaling factors or not

  • verify_names (bool) – (bool) whether to verify that all names in dict exist on block

Returns:

None

Raises:

TypeError if blk_or_suffix is not an instance of Block or Suffix –

idaes.core.scaling.util.scaling_factors_to_dict(blk_or_suffix, descend_into=True)[source]#

Write scaling factor and/or scaling hint suffixes to a serializable json dict. If a Block, indexed or otherwise is passed, this function collects both scaling factors and hints. If a suffix is passed directly, it serializes only that suffix (factors or hints) and leaves the other suffix (hints or factors) out of the resulting dict.

Component objects are replaced by their local names so they can be serialized.

Parameters:

  • blk_or_suffix – Pyomo Block or Suffix object to covert to dict

  • descend_into (bool) – for Blocks, whether to descend into any child blocks

Returns

dict containing scaling factors and/or scaling hints indexed by component names

Raises:

TypeError if blk_or_suffix is not an instance of Block or Suffix –

Parameters:

descend_into (bool)

idaes.core.scaling.util.scaling_factors_to_json_file(blk_or_suffix, filename)[source]#

Serialize scaling factors to file in json format.

Parameters:

  • blk_of_suffix – Block or Suffix to save scaling factors for

  • filename (str) – name of file to write to as string

Returns:

None

Raises:

TypeError if blk_or_suffix is not an instance of Block or Suffix –

idaes.core.scaling.util.set_scaling_factor(component, scaling_factor, overwrite=False)[source]#

Set scaling factor for component.

Scaling factors must be positive, non-zero floats.

Parameters:

  • component – component to set scaling factor for

  • scaling_factor (float) – scaling factor to assign

  • overwrite (bool) – (bool) whether to overwrite existing scaling factor

Returns:

None

Raises:

ValueError is scaling_factor is 0 or negative –

idaes.core.scaling.util.unscaled_constraints_generator(blk, descend_into=True)[source]#

Generator for unscaled constraints

Parameters:
Yields:

constraints with no scale factor

idaes.core.scaling.util.unscaled_variables_generator(blk, descend_into=True, include_fixed=False)[source]#

Generator for unscaled variables

Parameters:

  • block

  • blk (Block)

  • descend_into (<pyomo.core.base.set.DeclareGlobalSet.<locals>.GlobalSet object at 0x77a3e327aa50>)

  • include_fixed (<pyomo.core.base.set.DeclareGlobalSet.<locals>.GlobalSet object at 0x77a3e327aa50>)

Yields:

variables with no scale factor