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.

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.

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.

get_logger(model)

Get logger for model by name

get_output_level()

Get local output level.

This method returns either the local logger level set when calling initialize, or if that was not set then the logger level set in the Initializer configuration.

Returns:

Output level to use in log handler

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, output_level=None, exclude_unused_vars=False)

Execute full initialization routine.

Parameters:

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

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

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

• output_level – (optional) output level to use during initialization run (overrides global setting).

• exclude_unused_vars (bool) – whether to ignore unused variables when doing post-initialization checks.

Note - can only provide one of initial_guesses or json_file.

Returns:

InitializationStatus Enum

Parameters:

• model (Block) –

• initial_guesses (dict) –

• json_file (str) –

• exclude_unused_vars (bool) –

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 (dict) – dict of initial guesses to load.

• json_file (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 suppress 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 (dict) –

• json_file (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 (dict) – dict of initial guesses to load.

• json_file (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 (dict) –

• json_file (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 (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:

InitializationStatus 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 Blocks.

Parameters:

model (Block) – Pyomo Block to 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.

constraint_tolerance

Tolerance for checking constraint convergence

output_level

Set output level for logging messages

solver

Solver to use for initialization

solver_options

Dict of options to pass to solver

writer_config

Dict of writer_config arguments to pass to solver

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) – Initializer object to use for this/these submodels.

Returns:

None

cleanup(model, plugin_initializer_args, sub_initializers)

Post-initialization clean-up of plugins.

Iterates through model.initialization_order in reverse and calls plugin_cleanup method from the associated Initializer for each plugin.

Parameters:

• model – current model being initialized

• plugin_initializer_args – dict of arguments to be passed to plugin Initializer methods

• sub_initializers – dict of Initializers for each plugin

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.

initialization_routine(model, plugin_initializer_args=None, **kwargs)

Common initialization routine for models with plugins.

Parameters:

• model (Block) – Pyomo Block to be initialized

• plugin_initializer_args (dict) – dict-of-dicts containing arguments to be passed to plug-in Initializers. Keys should be submodel components.

• kwargs – case specific arguments to be passed to initialize_submodels method.

Returns:

Pyomo solver results object

initialize_main_model(model, **kwargs)

Placeholder method - derived classes should overload this with an appropriate initialization routine.

Parameters:

• model – current model being initialized

• **kwargs – placeholder for case specific arguments

Returns:

This method is expected to return a Pyomo solver results object

initialize_submodels(model, plugin_initializer_args, sub_initializers, **kwargs)

Initialize sub-models in order defined by model.initialization_order.

For the main model, self.initialize_main_model is called. For plugins, plugin_initialize is called from the associated Initializer.

Parameters:

• model – current model being initialized

• plugin_initializer_args – dict of arguments to be passed to plugin Initializer methods

• sub_initializers – dict of Initializers for each plugin

Returns:

Pyomo solver results object returned from self.initialize_main_model

prepare_plugins(model, plugin_initializer_args)

Prepare plugins for initialization.

Iterates through model.initialization_order and collects Initializer objects for each plugin and calls plugin_prepare for each.

Parameters:

• model – current model being initialized

• plugin_initializer_args – dict of arguments to be passed to plugin Initializer methods

Returns:

dict of Initializers indexed by plugin copy of plugin_initializer_args (to prevent mutation of origin dict)

solve_full_model(model, results)

Call solver on full model. If no plugins are present, just return results from previous solve step (main model).

Parameters:

• model – current model being initialized

• results – Pyomo solver results object from previous solver. This is used as the final state if no plugins are present.

Returns:

Pyomo solver results object