Control Volume Classes

Control Volumes are the center of the IDAES process modeling framework, and serve as the fundamental building block of all unit operations. Control Volumes represent a single, well-defined volume of material over which material, energy and/or momentum balances will be performed.

The IDAES Control Volume classes are designed to facilitate the construction of these balance equations by providing the model developer with a set of pre-built methods to perform the most common tasks in developing models of unit operations. The Control Volume classes contain methods for creating and linking the necessary property calculations and writing common forms of the balance equations so that the model developer can focus their time on the aspects that make each unit model unique.

The IDAES process modeling framework currently supports two types of Control Volume:

  • ControlVolume0DBlock represents a single well-mixed volume of material with a single inlet and a single outlet. This type of control volume is sufficient to model most inlet-outlet type unit operations which do not require spatial discretization.
  • ControlVolume1DBlock represents a volume with spatial variation in one dimension parallel to the material flow. This type of control volume is useful for representing flow in pipes and simple 1D flow reactors.

Common Control Volume Tasks

All of the IDAES Control Volume classes are built on a common core (ControlVolumeBlockData) which defines a set of common tasks required for all Control Volumes. The more specific Control Volume classes then build upon these common tasks to provide tools appropriate for their specific application.

All Control Volume classes begin with the following tasks:

  • Determine if the ControlVolume should be steady-state or dynamic.
  • Get the time domain.
  • Determine whether material and energy holdups should be calculated.
  • Collect information necessary for creating StateBlocks and ReactionBlocks.
  • Create references to phase_list and component_list Sets in the PhysicalParameterBlock.

More details on these steps is provided later.

Setting up the time domain

The first common task the Control Volume block performs is to determine if it should be dynamic or steady-state and to collect the time domain from the UnitModel. Control Volume blocks have an argument dynamic which can be provided during construction which specifies if the Control Volume should be dynamic (dynamic=True) or steady-state (dynamic=False). If the argument is not provided, the Control Volume block will inherit this argument from its parent UnitModel.

Finally, the Control Volume checks that the has_holdup argument is consistent with the dynamic argument, and raises a ConfigurationError if it is not.

Getting Property Package Information

If a reference to a property package was not provided by the UnitModel as an argument, the Control Volume first checks to see if the UnitModel has a property_package argument set, and uses this if present. Otherwise, the Control Volume block begins searching up the model tree looking for an argument named default_property_package and uses the first of these that it finds. If no default_property_package is found, a ConfigurationError is returned.

Collecting Indexing Sets for Property Package

The final common step for all Control Volumes is to collect any required indexing sets from the physical property package (for example component and phase lists). These are used by the Control Volume for determining what balance equations need to be written, and what terms to create.

The indexing sets the Control Volume looks for are:

  • component_list - used to determine what components are present, and thus what material balances are required
  • phase_list - used to determine what phases are present, and thus what balance equations are required

ControlVolume and ControlVolumeBlockData Classes

A key purpose of Control Volumes is to automate as much of the task of writing a unit model as possible. For this purpose, Control Volumes support a number of methods for common tasks model developers may want to perform. The specifics of these methods will be different between different types of Control Volumes, and certain methods may not be applicable to some types of Control Volumes (in which case a NotImplementedError will be returned). A full list of potential methods is provided here, however users should check the documentation for the specific Control Volume they are using for more details on what methods are supported in that specific Control Volume.

class idaes.core.control_volume_base.ControlVolume(*args, **kwargs)

This class is not usually used directly. Use ControlVolume0DBlock or ControlVolume1DBlock instead.

Parameters:
  • rule (function) – A rule function or None. Default rule calls build().
  • concrete (bool) – If True, make this a toplevel model. Default - False.
  • ctype (str) – Pyomo ctype of the block. Default - “Block”
  • default (dict) –

    Default ProcessBlockData config

    Keys
    dynamic
    Indicates whether this model will be dynamic, default - useDefault. Valid values: { useDefault - get flag from parent, True - set as a dynamic model, False - set as a steady-state model}
    has_holdup
    Indicates whether holdup terms should be constructed or not. Must be True if dynamic = True, default - False. Valid values: { True - construct holdup terms, False - do not construct holdup terms}
    property_package
    Property parameter object used to define property calculations, default - useDefault. Valid values: { useDefault - use default package from parent model or flowsheet, PropertyParameterObject - a PropertyParameterBlock object.}
    property_package_args
    A ConfigBlock with arguments to be passed to a property block(s) and used when constructing these, default - None. Valid values: { see property package for documentation.}
    reaction_package
    Reaction parameter object used to define reaction calculations, default - None. Valid values: { None - no reaction package, ReactionParameterBlock - a ReactionParameterBlock object.}
    reaction_package_args
    A ConfigBlock with arguments to be passed to a reaction block(s) and used when constructing these, default - None. Valid values: { see reaction package for documentation.}
    auto_construct
    If set to True, this argument will trigger the auto_construct method which will attempt to construct a set of material, energy and momentum balance equations based on the parent unit’s config block. The parent unit must have a config block which derives from CONFIG_Base, default - False. Valid values: { True - use automatic construction, False - do not use automatic construciton.}
  • initialize (dict) – ProcessBlockData config for individual elements. Keys are BlockData indexes and values are dictionaries described under the “default” argument above.
  • idx_map (function) – Function to take the index of a BlockData element and return the index in the initialize dict from which to read arguments. This can be provided to overide the default behavior of matching the BlockData index exactly to the index in initialize.
Returns:

(ControlVolume) New instance
class idaes.core.control_volume_base.ControlVolumeBlockData(component)[source]

The ControlVolumeBlockData Class forms the base class for all IDAES ControlVolume models. The purpose of this class is to automate the tasks common to all control volume blockss and ensure that the necessary attributes of a control volume block are present.

The most signfiicant role of the ControlVolumeBlockData class is to set up the construction arguments for the control volume block, automatically link to the time domain of the parent block, and to get the information about the property and reaction packages.

add_energy_balances(balance_type=<EnergyBalanceType.useDefault: -1>, **kwargs)[source]

General method for adding energy balances to a control volume. This method makes calls to specialised sub-methods for each type of energy balance.

Parameters:
  • balance_type (EnergyBalanceType) – Enum indicating which type of energy balance should be constructed.
  • has_heat_of_reaction (bool) – whether terms for heat of reaction should be included in energy balance
  • has_heat_transfer (bool) – whether generic heat transfer terms should be included in energy balances
  • has_work_transfer (bool) – whether generic mass transfer terms should be included in energy balances
  • custom_term (Expression) – a Pyomo Expression representing custom terms to be included in energy balances
Returns:

Constraint objects constructed by sub-method
add_geometry(*args, **kwargs)[source]

Method for defining the geometry of the control volume.

See specific control volume documentation for details.

add_material_balances(balance_type=<MaterialBalanceType.useDefault: -1>, **kwargs)[source]

General method for adding material balances to a control volume. This method makes calls to specialised sub-methods for each type of material balance.

Parameters:
  • - MaterialBalanceType Enum indicating which type of (balance_type) – material balance should be constructed.
  • - whether default generation terms for rate (has_rate_reactions) – reactions should be included in material balances
  • - whether generation terms should for (has_equilibrium_reactions) – chemical equilibrium reactions should be included in material balances
  • - whether generation terms should for phase (has_phase_equilibrium) – equilibrium behaviour should be included in material balances
  • - whether generic mass transfer terms should be (has_mass_transfer) – included in material balances
  • - a Pyomo Expression representing custom terms to (custom_mass_term) – be included in material balances on a molar basis.
  • - a Pyomo Expression representing custom terms to – be included in material balances on a mass basis.
Returns:

Constraint objects constructed by sub-method
add_momentum_balances(balance_type=<MomentumBalanceType.pressureTotal: 1>, **kwargs)[source]

General method for adding momentum balances to a control volume. This method makes calls to specialised sub-methods for each type of momentum balance.

Parameters:
  • balance_type (MomentumBalanceType) – Enum indicating which type of momentum balance should be constructed. Default = MomentumBalanceType.pressureTotal.
  • has_pressure_change (bool) – whether default generation terms for pressure change should be included in momentum balances
  • custom_term (Expression) – a Pyomo Expression representing custom terms to be included in momentum balances
Returns:

Constraint objects constructed by sub-method
add_phase_component_balances(*args, **kwargs)[source]

Method for adding material balances indexed by phase and component to the control volume.

See specific control volume documentation for details.

add_phase_energy_balances(*args, **kwargs)[source]

Method for adding energy balances (including kinetic energy) indexed by phase to the control volume.

See specific control volume documentation for details.

add_phase_enthalpy_balances(*args, **kwargs)[source]

Method for adding enthalpy balances indexed by phase to the control volume.

See specific control volume documentation for details.

add_phase_momentum_balances(*args, **kwargs)[source]

Method for adding momentum balances indexed by phase to the control volume.

See specific control volume documentation for details.

add_phase_pressure_balances(*args, **kwargs)[source]

Method for adding pressure balances indexed by phase to the control volume.

See specific control volume documentation for details.

add_reaction_blocks(*args, **kwargs)[source]

Method for adding ReactionBlocks to the control volume.

See specific control volume documentation for details.

add_state_blocks(*args, **kwargs)[source]

Method for adding StateBlocks to the control volume.

See specific control volume documentation for details.

add_total_component_balances(*args, **kwargs)[source]

Method for adding material balances indexed by component to the control volume.

See specific control volume documentation for details.

add_total_element_balances(*args, **kwargs)[source]

Method for adding total elemental material balances indexed to the control volume.

See specific control volume documentation for details.

add_total_energy_balances(*args, **kwargs)[source]

Method for adding a total energy balance (including kinetic energy) to the control volume.

See specific control volume documentation for details.

add_total_enthalpy_balances(*args, **kwargs)[source]

Method for adding a total enthalpy balance to the control volume.

See specific control volume documentation for details.

add_total_material_balances(*args, **kwargs)[source]

Method for adding a total material balance to the control volume.

See specific control volume documentation for details.

add_total_momentum_balances(*args, **kwargs)[source]

Method for adding a total momentum balance to the control volume.

See specific control volume documentation for details.

add_total_pressure_balances(*args, **kwargs)[source]

Method for adding a total pressure balance to the control volume.

See specific control volume documentation for details.

build()[source]

General build method for Control Volumes blocks. This method calls a number of sub-methods which automate the construction of expected attributes of all ControlVolume blocks.

Inheriting models should call super().build.

Parameters:None –
Returns:None

Auto-Construct Method

To reduce the demands on unit model developers even further, Control Volumes have an optional auto-construct feature that will attempt to populate the Control Volume based on a set of instructions provided at the Unit Model level. If the auto_construct configuration argument is set to True, the following methods are called automatically in the following order when instantiating the Control Volume.

  1. add_geometry
  2. add_state_blocks
  3. add_reaction_blocks
  4. add_material_balances
  5. add_energy_balances
  6. add_momentum_balances
  7. apply_transformation

To determine what terms are required for the balance equations, the Control Volume expects the Unit Model to have the following configuration arguments, which are used as arguments to the methods above.

  • dynamic
  • has_holdup
  • material_balance_type
  • energy_balance_type
  • momentum_balance_type
  • has_rate_reactions
  • has_equilibrium_reactions
  • has_phase_equilibrium
  • has_mass_transfer
  • has_heat_of_reaction
  • has_heat_transfer
  • has_work_transfer
  • has_pressure_change
  • property_package
  • property_package_args
  • reaction_package
  • reaction_package_args

For convenience, a template ConfigBlock (named CONFIG_Template) is available in the control_volume_base.py module which contains all the necessary arguments which can be inherited by unit models wishing to use the auto-construct feature.