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
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)[source]¶
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)[source]¶
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)[source]¶
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_output_level()[source]¶
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)[source]¶
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
- initialize(model, initial_guesses=None, json_file=None, output_level=None, exclude_unused_vars=False)[source]¶
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.
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.
- load_initial_guesses(model, initial_guesses=None, json_file=None, exception_on_fixed=True)[source]¶
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 suppress exceptions when guess provided for a fixed variable (default=True).
Note - can only provide one of initial_guesses or json_file.
- plugin_finalize(plugin)[source]¶
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)[source]¶
Initialize plug-in model. This activates the Block and then calls self.initialize(plugin).
Derived Initializers should overload this as required.
- Parameters
Note - can only provide one of initial_guesses or json_file.
- plugin_prepare(plugin)[source]¶
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)[source]¶
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
InitializationStatus Enum
- precheck(model)[source]¶
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)[source]¶
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)[source]¶
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
- 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)[source]¶
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)[source]¶
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)[source]¶
Lookup Initializer object to use for specified sub-model.
This method will return Initializers in the following order:
Initializer defined for a specific submodel.
Initializer defined for a type of model (e.g. UnitModel).
submodel.default_initializer (if present).
Initializer for submodel.params (in case of StateBlocks and ReactionBlocks).
Global default Initializer defined in config.default_submodel_initializer.
None.
- Parameters
submodel (Block) – sub-model to get initializer for.
- Returns
Initializer object or None.
- initialization_routine(model, plugin_initializer_args=None, **kwargs)[source]¶
Common initialization routine for models with plugins.
- Parameters
- Returns
Pyomo solver results object
- initialize_main_model(model, **kwargs)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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