1D Control Volume Class¶
The ControlVolume1DBlock block is used for systems with one spatial dimension where material flows parallel to the spatial domain. Examples of these types of unit operations include plug flow reactors and pipes. ControlVolume1DBlock blocks are discretized along the length domain and contain one StateBlock and one ReactionBlock (if applicable) at each point in the domain (including the inlet and outlet).
- class idaes.core.control_volume1d.ControlVolume1DBlock(*args, **kwds)¶
ControlVolume1DBlock is a specialized Pyomo block for IDAES control volume blocks discretized in one spatial direction, and contains instances of ControlVolume1DBlockData.
ControlVolume1DBlock should be used for any control volume with a defined volume and distinct inlets and outlets where there is a single spatial domain parallel to the material flow direction. This encompases unit operations such as plug flow reactors and pipes.
- Parameters
rule (function) – A rule function or None. Default rule calls build().
concrete (bool) – If True, make this a toplevel model. Default - False.
ctype (class) – Pyomo ctype of the block. Default - pyomo.environ.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.}
- area_definition
Argument defining whether area variable should be spatially variant or not. default - DistributedVars.uniform. Valid values: { DistributedVars.uniform - area does not vary across spatial domian, DistributedVars.variant - area can vary over the domain and is indexed by time and space.}
- transformation_method
Method to use to transform domain. Must be a method recognised by the Pyomo TransformationFactory.
- transformation_scheme
Scheme to use when transforming domain. See Pyomo documentation for supported schemes.
- finite_elements
Number of finite elements to use in transformation (equivalent to Pyomo nfe argument).
- collocation_points
Number of collocation points to use (equivalent to Pyomo ncp argument).
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
(ControlVolume1DBlock) New instance
- class idaes.core.control_volume1d.ControlVolume1DBlockData(component)[source]¶
1-Dimensional ControlVolume Class
This class forms the core of all 1-D IDAES models. It provides methods to build property and reaction blocks, and add mass, energy and momentum balances. The form of the terms used in these constraints is specified in the chosen property package.
- add_geometry(length_domain=None, length_domain_set=None, length_var=None, flow_direction=FlowDirection.forward)[source]¶
Method to create spatial domain and volume Var in ControlVolume.
- Parameters
- (length_var) – domain for the ControlVolume. If not provided, a new ContinuousSet will be created (default=None). ContinuousSet should be normalized to run between 0 and 1.
- – a new ContinuousSet if length_domain is not provided (default = [0.0, 1.0]).
- – the spatial domain,. If a variable is provided, a reference will be made to this in place of the length Var.
flow (flow_direction - argument indicating direction of material) –
- relative to length domain. Valid values:
FlowDirection.forward (default), flow goes from 0 to 1.
FlowDirection.backward, flow goes from 1 to 0
- Returns
None
- add_phase_component_balances(has_rate_reactions=False, has_equilibrium_reactions=False, has_phase_equilibrium=False, has_mass_transfer=False, custom_molar_term=None, custom_mass_term=None)[source]¶
This method constructs a set of 1D material balances indexed by time, length, phase and component.
- Parameters
has_rate_reactions – whether default generation terms for rate reactions should be included in material balances
has_equilibrium_reactions – whether generation terms should for chemical equilibrium reactions should be included in material balances
has_phase_equilibrium – whether generation terms should for phase equilibrium behaviour should be included in material balances
has_mass_transfer – whether generic mass transfer terms should be included in material balances
custom_molar_term – a Pyomo Expression representing custom terms to be included in material balances on a molar basis. Expression must be indexed by time, length domain, phase list and component list
custom_mass_term – a Pyomo Expression representing custom terms to be included in material balances on a mass basis. Expression must be indexed by time, length domain, phase list and component list
- Returns
Constraint object representing material balances
- 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(has_equilibrium=None)[source]¶
This method constructs the reaction block for the control volume.
- Parameters
has_equilibrium – indicates whether equilibrium calculations will be required in reaction block
package_arguments – dict-like object of arguments to be passed to reaction block as construction arguments
- Returns
None
- add_state_blocks(information_flow=FlowDirection.forward, has_phase_equilibrium=None)[source]¶
This method constructs the state blocks for the control volume.
- Parameters
information_flow – a FlowDirection Enum indicating whether information flows from inlet-to-outlet or outlet-to-inlet
has_phase_equilibrium – indicates whether equilibrium calculations will be required in state blocks
package_arguments – dict-like object of arguments to be passed to state blocks as construction arguments
- Returns
None
- add_total_component_balances(has_rate_reactions=False, has_equilibrium_reactions=False, has_phase_equilibrium=False, has_mass_transfer=False, custom_molar_term=None, custom_mass_term=None)[source]¶
This method constructs a set of 1D material balances indexed by time length and component.
- Parameters
has_rate_reactions – whether default generation terms for rate reactions should be included in material balances
has_equilibrium_reactions – whether generation terms should for chemical equilibrium reactions should be included in material balances
has_phase_equilibrium – whether generation terms should for phase equilibrium behaviour should be included in material balances
has_mass_transfer – whether generic mass transfer terms should be included in material balances
custom_molar_term – a Pyomo Expression representing custom terms to be included in material balances on a molar basis. Expression must be indexed by time, length domain and component list
custom_mass_term – a Pyomo Expression representing custom terms to be included in material balances on a mass basis. Expression must be indexed by time, length domain and component list
- Returns
Constraint object representing material balances
- add_total_element_balances(has_rate_reactions=False, has_equilibrium_reactions=False, has_phase_equilibrium=False, has_mass_transfer=False, custom_elemental_term=None)[source]¶
This method constructs a set of 1D element balances indexed by time and length.
- Parameters
rate (has_rate_reactions - whether default generation terms for) – reactions should be included in material balances
for (has_equilibrium_reactions - whether generation terms should) – chemical equilibrium reactions should be included in material balances
phase (has_phase_equilibrium - whether generation terms should for) – equilibrium behaviour should be included in material balances
be (has_mass_transfer - whether generic mass transfer terms should) – included in material balances
custom (custom_elemental_term - a Pyomo Expression representing) – terms to be included in material balances on a molar elemental basis. Expression must be indexed by time, length and element list
- Returns
Constraint object representing material balances
- 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(has_heat_of_reaction=False, has_heat_transfer=False, has_work_transfer=False, has_enthalpy_transfer=False, custom_term=None)[source]¶
This method constructs a set of 1D enthalpy balances indexed by time and phase.
- Parameters
should (has_heat_of_reaction - whether terms for heat of reaction) – be included in enthalpy balance
be (has_work_transfer - whether terms for work transfer should) – included in enthalpy balances
be – included in enthalpy balances
to (custom_term - a Pyomo Expression representing custom terms) – mass transfer should be included in enthalpy balance. This should generally be the same as the has_mass_transfer argument in the material balance methods
to – be included in enthalpy balances. Expression must be indexed by time, length and phase list
- Returns
Constraint object representing enthalpy balances
- 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(has_pressure_change=False, custom_term=None)[source]¶
This method constructs a set of 1D pressure balances indexed by time.
- Parameters
be (has_pressure_change - whether terms for pressure change should) – included in enthalpy balances
to (custom_term - a Pyomo Expression representing custom terms) – be included in pressure balances. Expression must be indexed by time and length domain
- Returns
Constraint object representing pressure balances
- apply_transformation()[source]¶
Method to apply DAE transformation to the Control Volume length domain. Transformation applied will be based on the Control Volume configuration arguments.
- initialize(state_args=None, outlvl=0, optarg=None, solver=None, hold_state=True)[source]¶
Initialization routine for 1D control volume.
- Keyword Arguments
state_args – a dict of arguments to be passed to the property package(s) to provide an initial state for initialization (see documentation of the specific property package) (default = {}).
outlvl – sets output level of initialization routine
optarg – solver options dictionary object (default=None, use default solver options)
solver – str indicating which solver to use during initialization (default = None)
hold_state – flag indicating whether the initialization routine should unfix any state variables fixed during initialization, default - True. Valid values: True - states variables are not unfixed, and a dict of returned containing flags for which states were fixed during initialization, False - state variables are unfixed after initialization by calling the release_state method.
- Returns
If hold_states is True, returns a dict containing flags for which states were fixed during initialization else the release state is triggered.
- model_check()[source]¶
This method executes the model_check methods on the associated state blocks (if they exist). This method is generally called by a unit model as part of the unit’s model_check method.
- Parameters
None –
- Returns
None
- release_state(flags, outlvl=0)[source]¶
Method to release state variables fixed during initialization.
- Keyword Arguments
flags – dict containing information of which state variables were fixed during initialization, and should now be unfixed. This dict is returned by initialize if hold_state = True.
outlvl – sets output level of logging
- Returns
None
ControlVolume1DBlock Equations¶
This section documents the variables and constraints created by each of the methods provided by the ControlVolume0DBlock class.
\(t\) indicates time index
\(x\) indicates spatial (length) index
\(p\) indicates phase index
\(j\) indicates component index
\(e\) indicates element index
\(r\) indicates reaction name index
Most terms within the balance equations written by ControlVolume1DBlock are on a basis of per unit length (e.g. \(mol/m \cdot s\)).
add_geometry¶
The add_geometry method creates the normalized length domain for the control volume (or a reference to an external domain). All constraints in ControlVolume1DBlock assume a normalized length domain, with values between 0 and 1.
This method also adds variables and constraints to describe the geometry of the control volume. ControlVolume1DBlock does not support varying dimensions of the control volume with time at this stage.
Variables
Variable Name |
Symbol |
Indices |
Conditions |
---|---|---|---|
length_domain |
\(x\) |
None |
None |
volume |
\(V\) |
None |
None |
area |
\(A\) |
None |
None |
length |
\(L\) |
None |
If length_var argument is provided, a reference to the provided component is made in place of creating a new variable |
Constraints
geometry_constraint:
add_phase_component_balances¶
Material balances are written for each component in each phase (e.g. separate balances for liquid water and steam). Physical property packages may include information to indicate that certain species do not appear in all phases, and material balances will not be written in these cases (if has_holdup is True holdup terms will still appear for these species, however these will be set to 0).
Variables
Variable Name |
Symbol |
Indices |
Conditions |
---|---|---|---|
material_holdup |
\(M_{t,x,p,j}\) |
t, x, p, j |
has_holdup = True |
phase_fraction |
\(\phi_{t,x,p}\) |
t, x, p |
has_holdup = True |
material_accumulation |
\(\frac{\partial M_{t,x,p,j}}{\partial t}\) |
t, x, p, j |
dynamic = True |
_flow_terms |
\(F_{t, x, p, j}\) |
t, x, p, j |
None |
material_flow_dx |
\(\frac{\partial F_{t,x,p,j}}{\partial x}\) |
t, x, p, j |
None |
rate_reaction_generation |
\(N_{kinetic,t,x,p,j}\) |
t, x, p ,j |
has_rate_reactions = True |
rate_reaction_extent |
\(X_{kinetic,t,x,r}\) |
t, x, r |
has_rate_reactions = True |
equilibrium_reaction_generation |
\(N_{equilibrium,t,x,p,j}\) |
t, x, p ,j |
has_equilibrium_reactions = True |
equilibrium_reaction_extent |
\(X_{equilibrium,t,x,r}\) |
t, x, r |
has_equilibrium_reactions = True |
phase_equilibrium_generation |
\(N_{pe,t,x,p,j}\) |
t, x, p ,j |
has_phase_equilibrium = True |
mass_transfer_term |
\(N_{transfer,t,x,p,j}\) |
t, x, p ,j |
has_mass_transfer = True |
Constraints
material_balances(t, x, p, j):
\(fd\) is a flow direction term, which allows for material flow to be defined in either direction. If material flow is defined as forward, \(fd = -1\), otherwise \(fd = 1\).
The \(N_{custom, t, x, p, j}\) term allows the user to provide custom terms (variables or expressions) in both mass and molar basis which will be added into the material balances, which will be converted as necessary to the same basis as the material balance (by multiplying or dividing by the component molecular weight). The basis of the material balance is determined by the physical property package, and if undefined (or not mass or mole basis), an Exception will be returned.
material_flow_linking_constraints(t, x, p, j):
This constraint is an internal constraint used to link the extensive material flow terms in the StateBlocks into a single indexed variable. This is required as Pyomo.DAE requires a single indexed variable to create the associated DerivativeVars and their numerical expansions.
If has_holdup is True, material_holdup_calculation(t, x, p, j):
where \(\rho_{t, x, p ,j}\) is the density of component \(j\) in phase \(p\) at time \(t\) and location \(x\).
If dynamic is True:
Numerical discretization of the derivative terms, \(\frac{\partial M_{t,x,p,j}}{\partial t}\), will be performed by Pyomo.DAE.
If has_rate_reactions is True, rate_reaction_stoichiometry_constraint(t, x, p, j):
where \(\alpha_{r, p. j}\) is the stoichiometric coefficient of component \(j\) in phase \(p\) for reaction \(r\) (as defined in the PhysicalParameterBlock).
If has_equilibrium_reactions argument is True, equilibrium_reaction_stoichiometry_constraint(t, x, p, j):
where \(\alpha_{r, p. j}\) is the stoichiometric coefficient of component \(j\) in phase \(p\) for reaction \(r\) (as defined in the PhysicalParameterBlock).
add_total_component_balances¶
Material balances are written for each component across all phases (e.g. one balance for both liquid water and steam). Physical property packages may include information to indicate that certain species do not appear in all phases, and material balances will not be written in these cases (if has_holdup is True holdup terms will still appear for these species, however these will be set to 0).
Variables
Variable Name |
Symbol |
Indices |
Conditions |
---|---|---|---|
material_holdup |
\(M_{t,x,p,j}\) |
t, x, p, j |
has_holdup = True |
phase_fraction |
\(\phi_{t,x,p}\) |
t, x, p |
has_holdup = True |
material_accumulation |
\(\frac{\partial M_{t,x,p,j}}{\partial t}\) |
t, x, p, j |
dynamic = True |
_flow_terms |
\(F_{t, x, p, j}\) |
t, x, p, j |
None |
material_flow_dx |
\(\frac{\partial F_{t,x,p,j}}{\partial x}\) |
t, x, p, j |
None |
rate_reaction_generation |
\(N_{kinetic,t,x,p,j}\) |
t, x, p ,j |
has_rate_reactions = True |
rate_reaction_extent |
\(X_{kinetic,t,x,r}\) |
t, x, r |
has_rate_reactions = True |
equilibrium_reaction_generation |
\(N_{equilibrium,t,x,p,j}\) |
t, x, p ,j |
has_equilibrium_reactions = True |
equilibrium_reaction_extent |
\(X_{equilibrium,t,x,r}\) |
t, x, r |
has_equilibrium_reactions = True |
mass_transfer_term |
\(N_{transfer,t,x,p,j}\) |
t, x, p ,j |
has_mass_transfer = True |
Constraints
material_balances(t, x, p, j):
\(fd\) is a flow direction term, which allows for material flow to be defined in either direction. If material flow is defined as forward, \(fd = -1\), otherwise \(fd = 1\).
The \(N_{custom, t, x, j}\) term allows the user to provide custom terms (variables or expressions) in both mass and molar basis which will be added into the material balances, which will be converted as necessary to the same basis as the material balance (by multiplying or dividing by the component molecular weight). The basis of the material balance is determined by the physical property package, and if undefined (or not mass or mole basis), an Exception will be returned.
material_flow_linking_constraints(t, x, p, j):
This constraint is an internal constraint used to link the extensive material flow terms in the StateBlocks into a single indexed variable. This is required as Pyomo.DAE requires a single indexed variable to create the associated DerivativeVars and their numerical expansions.
If has_holdup is True, material_holdup_calculation(t, x, p, j):
where \(\rho_{t, x, p ,j}\) is the density of component \(j\) in phase \(p\) at time \(t\) and location \(x\).
If dynamic is True:
Numerical discretization of the derivative terms, \(\frac{\partial M_{t,x,p,j}}{\partial t}\), will be performed by Pyomo.DAE.
If has_rate_reactions is True, rate_reaction_stoichiometry_constraint(t, x, p, j):
where \(\alpha_{r, p. j}\) is the stoichiometric coefficient of component \(j\) in phase \(p\) for reaction \(r\) (as defined in the PhysicalParameterBlock).
If has_equilibrium_reactions argument is True, equilibrium_reaction_stoichiometry_constraint(t, x, p, j):
where \(\alpha_{r, p. j}\) is the stoichiometric coefficient of component \(j\) in phase \(p\) for reaction \(r\) (as defined in the PhysicalParameterBlock).
add_total_element_balances¶
Material balances are written for each element in the mixture.
Variables
Variable Name |
Symbol |
Indices |
Conditions |
---|---|---|---|
element_holdup |
\(M_{t,x,e}\) |
t, x, e |
has_holdup = True |
phase_fraction |
\(\phi_{t,x,p}\) |
t, x, p |
has_holdup = True |
element_accumulation |
\(\frac{\partial M_{t,x,e}}{\partial t}\) |
t, x, e |
dynamic = True |
elemental_mass_transfer_term |
\(N_{transfer,t,x,e}\) |
t, x, e |
has_mass_transfer = True |
elemental_flow_term |
\(F_{t,x,e}\) |
t, x, e |
None |
Constraints
elemental_flow_constraint(t, x, e):
where \(n_{j, e}\) is the number of moles of element \(e\) in component \(j\).
element_balances(t, x, e):
\(fd\) is a flow direction term, which allows for material flow to be defined in either direction. If material flow is defined as forward, \(fd = -1\), otherwise \(fd = 1\).
The \(N_{custom, t, x, e}\) term allows the user to provide custom terms (variables or expressions) which will be added into the material balances.
If has_holdup is True, elemental_holdup_calculation(t, x, e):
where \(\rho_{t, x, p ,j}\) is the density of component \(j\) in phase \(p\) at time \(t\) and location \(x\).
If dynamic is True:
Numerical discretization of the derivative terms, \(\frac{\partial M_{t,x,p,j}}{\partial t}\), will be performed by Pyomo.DAE.
add_total_enthalpy_balances¶
A single enthalpy balance is written for the entire mixture at each point in the spatial domain.
Variables
Variable Name |
Symbol |
Indices |
Conditions |
---|---|---|---|
energy_holdup |
\(E_{t,x,p}\) |
t, x, p |
has_holdup = True |
phase_fraction |
\(\phi_{t,x,p}\) |
t, x, p |
has_holdup = True |
energy_accumulation |
\(\frac{\partial E_{t,x,p}}{\partial t}\) |
t, x, p |
dynamic = True |
_enthalpy_flow |
\(H_{t,x,p}\) |
t, x, p |
None |
enthalpy_flow_dx |
\(\frac{\partial H_{t,x,p}}{\partial x}\) |
t, x, p |
None |
heat |
\(Q_{t,x}\) |
t, x |
has_heat_transfer = True |
work |
\(W_{t,x}\) |
t, x |
has_work_transfer = True |
enthalpy_transfer |
\(H_{transfer,t,x}\) |
t, x |
has_enthalpy_transfer = True |
Expressions
heat_of_reaction(t, x):
where \(Q_{rxn, t, x}\) is the total enthalpy released by both kinetic and equilibrium reactions, and \(\Delta H_{rxn, r}\) is the specific heat of reaction for reaction \(r\).
Parameters
Parameter Name |
Symbol |
Default Value |
---|---|---|
scaling_factor_energy |
\(s_{energy}\) |
1E-6 |
Constraints
enthalpy_balance(t):
\(fd\) is a flow direction term, which allows for material flow to be defined in either direction. If material flow is defined as forward, \(fd = -1\), otherwise \(fd = 1\).
The \(E_{custom, t, x}\) term allows the user to provide custom terms which will be added into the energy balance.
enthalpy_flow_linking_constraints(t, x, p):
This constraint is an internal constraint used to link the extensive enthalpy flow terms in the StateBlocks into a single indexed variable. This is required as Pyomo.DAE requires a single indexed variable to create the associated DerivativeVars and their numerical expansions.
If has_holdup is True, enthalpy_holdup_calculation(t, x, p):
where \(u_{t, x, p}\) is the internal density (specific internal energy) of phase \(p\) at time \(t\) and location \(x\).
If dynamic is True:
Numerical discretization of the derivative terms, \(\frac{\partial E_{t,x,p}}{\partial t}\), will be performed by Pyomo.DAE.
add_total_pressure_balances¶
A single pressure balance is written for the entire mixture at all points in the spatial domain.
Variables
Variable Name |
Symbol |
Indices |
Conditions |
---|---|---|---|
pressure |
\(P_{t,x}\) |
t, x |
None |
pressure_dx |
\(\frac{\partial P_{t,x}}{\partial x}\) |
t, x |
None |
deltaP |
\(\Delta P_{t,x}\) |
t, x |
has_pressure_change = True |
Parameters
Parameter Name |
Symbol |
Default Value |
---|---|---|
scaling_factor_pressure |
\(s_{pressure}\) |
1E-4 |
Constraints
pressure_balance(t, x):
\(fd\) is a flow direction term, which allows for material flow to be defined in either direction. If material flow is defined as forward, \(fd = -1\), otherwise \(fd = 1\).
The \(\Delta P_{custom, t, x}\) term allows the user to provide custom terms which will be added into the pressure balance.
pressure_linking_constraint(t, x):
This constraint is an internal constraint used to link the pressure terms in the StateBlocks into a single indexed variable. This is required as Pyomo.DAE requires a single indexed variable to create the associated DerivativeVars and their numerical expansions.