Developing Custom Initializers

To assist users with developing custom Initializer objects, the IDAES-IP provides two base classes which define the standard API for Initializer objects and methods for performing common activities.

Contents

• Developing Custom Initializers

  • Standard API

  • InitializerBase Class

  • ModularInitializerBase Class

The InitializerBase class defines the standard API for Initializer objects, whilst the ModularInitializerBase class extends this with some methods useful for defining hierarchical initialization routines.

Standard API

All Initializer objects are expected to define an initialize method which will be called in order to run the initialization routine. This method may in turn call other supporting methods, and the base classes provide pre-defined methods for common tasks such as fixing and restoring degrees of freedom and performing pre- and post-initialization checks. Custom routines are not required to make use of these methods, and may overload these with custom methods if desired.

Initializers intended for “plug-in” type models (i.e., models attached to other models after the parent model has been constructed) and used as part of hierarchical initialization routine should also implement the plugin_prepare, plugin_initialize and plugin_finalize methods as necessary.

InitializerBase Class

class idaes.core.initialization.initializer_base.InitializerBase(**kwargs)

Base class for Initializer objects.

This implements a default workflow and methods for common tasks. Developers should feel free to overload these as necessary.

Keyword Arguments

• constraint_tolerance – Tolerance for checking constraint convergence

• output_level – Set output level for logging messages

fix_initialization_states(model)

Call to model.fix_initialization_states method. Method will pass if fix_initialization_states not found.

Parameters

model (Block) – Pyomo Block to fix states on.

Returns

None

get_current_state(model)

Get and store current state of variables (fixed/unfixed) and constraints/objectives activated/deactivated in model.

Parameters

model (Block) – Pyomo model to get state from.

Returns

dict serializing current model state.

initialization_routine(model)

Placeholder method to run initialization routine. Derived classes should overload this with the desired routine.

Parameters

model (Block) – Pyomo Block to initialize.

Returns

Overloaded method should return a Pyomo solver results object is available, otherwise None

Raises

NotImplementedError –

initialize(model, initial_guesses=None, json_file=None)

Execute full initialization routine.

Parameters

• model (Block) – Pyomo model to be initialized.

• initial_guesses (Optional[dict]) – dict of initial guesses to load.

• json_file (Optional[str]) – file name of json file to load initial guesses from as str.

Note - can only provide one of initial_guesses or json_file.

Returns

InitializationStatus Enum

Parameters

• model (Block) –

• initial_guesses (Optional[dict]) –

• json_file (Optional[str]) –

load_initial_guesses(model, initial_guesses=None, json_file=None, exception_on_fixed=True)

Load initial guesses for variables into model.

Parameters

• model (Block) – Pyomo model to be initialized.

• initial_guesses (Optional[dict]) – dict of initial guesses to load.

• json_file (Optional[str]) – file name of json file to load initial guesses from as str.

• exception_on_fixed (bool) – (optional, initial_guesses only) bool indicating whether to supress exceptions when guess provided for a fixed variable (default=True).

Note - can only provide one of initial_guesses or json_file.

Returns

None

Raises

ValueError if both initial_guesses and json_file are provided. –

Parameters

• model (Block) –

• initial_guesses (Optional[dict]) –

• json_file (Optional[str]) –

• exception_on_fixed (bool) –

plugin_finalize(plugin)

Final clean up of plug-ins after initialization. This method does nothing.

Derived Initializers should overload this as required.

Parameters

plugin – model to be cleaned-up after initialization

Returns

None.

plugin_initialize(plugin, initial_guesses=None, json_file=None)

Initialize plug-in model. This activates the Block and then calls self.initialize(plugin).

Derived Initializers should overload this as required.

Parameters

• plugin (Block) – Pyomo model to be initialized.

• initial_guesses (Optional[dict]) – dict of initial guesses to load.

• json_file (Optional[str]) – file name of json file to load initial guesses from as str.

Note - can only provide one of initial_guesses or json_file.

Returns

InitializationStatus Enum

Parameters

• plugin (Block) –

• initial_guesses (Optional[dict]) –

• json_file (Optional[str]) –

plugin_prepare(plugin)

Prepare plug-in model for initialization. This deactivates the plug-in model.

Derived Initializers should overload this as required.

Parameters

plugin (Block) – model to be prepared for initialization

Returns

None.

postcheck(model, results_obj=None, exclude_unused_vars=False)

Check the model has been converged after initialization.

If a results_obj is provided, this will be checked using check_optimal_termination, otherwise this will walk all constraints in the model and check that they are within tolerance (set via the Initializer constraint_tolerance config argument).

Parameters

• model (Block) – model to be checked for convergence.

• results_obj (Optional[dict]) – Pyomo solver results dict (if applicable, default=None).

• exclude_unused_vars (bool) – bool indicating whether to check if uninitialized vars appear in active constraints and ignore if this is the case. Checking for unused vars required determining the set of variables in active constraint. Default = False.

Returns

InitialationStatus Enum

precheck(model)

Check for satisfied degrees of freedom before running initialization.

Parameters

model (Block) – Pyomo Block to fix states on.

Returns

None

Raises

InitializationError if Degrees of Freedom do not equal 0. –

restore_model_state(model)

Restore model state to that stored in self.initial_state.

This method restores the following:

• fixed status of all variables,

• value of any fixed variables,

• active status of all Constraints and Blcoks.

Parameters

model (Block) – Pyomo Block ot restore state on.

Returns

None

Raises

ValueError if no initial state is stored. –

ModularInitializerBase Class

class idaes.core.initialization.initializer_base.ModularInitializerBase(**kwargs)

Base class for modular Initializer objects.

This extends the base Initializer class to include attributes and methods for defining initializer objects for sub-models. :keyword constraint_tolerance: Tolerance for checking constraint convergence :keyword output_level: Set output level for logging messages :keyword default_submodel_initializer: Default Initializer object to use for sub-models. Only used if no Initializer defined in submodel_initializers.

add_submodel_initializer(submodel, initializer)

Define an Initializer for a give submodel or type of submodel.

Parameters

• submodel (Block) – submodel or type of submodel to define Initializer for.

• initializer (InitializerBase) – Initalizer object to use for this/these submodels.

Returns

None

get_submodel_initializer(submodel)

Lookup Initializer object to use for specified sub-model.

This method will return Initializers in the following order:

1. Initializer defined for a specific submodel.

2. Initializer defined for a type of model (e.g. UnitModel).

3. submodel.default_initializer (if present).

4. Initializer for submodel.params (in case of StateBlocks and ReactionBlocks).

5. Global default Initializer defined in config.default_submodel_initializer.

6. None.

Parameters

submodel (Block) – sub-model to get initializer for.

Returns

Initializer object or None.