Warning

This documentation is for an old version of Cantera. You can find docs for newer versions here.

Zero-Dimensional Reactor Networks

Func

class Func(typ, n, p)

Func class constructor.

A class for functors. A functor is an object that behaves like a function. Cantera defines a set of functors to use to create arbitrary functions to specify things like heat fluxes, piston speeds, etc., in reactor network simulations. Of course, they can be used for other things too.

The main feature of a functor class is that it overloads the () operator to evaluate the function. For example, suppose object f is a functor that evaluates the polynomial \(2x^2 - 3x + 1\). Then writing f(2) would cause the method that evaluates the function to be invoked, and would pass it the argument 2. The return value would of course be 3.

The types of functors you can create in Cantera are these:

  1. A polynomial
  2. A Fourier series
  3. A sum of Arrhenius terms
  4. A Gaussian.

You can also create composite functors by adding, multiplying, or dividing these basic functors, or other composite functors.

Note: this MATLAB class shadows the underlying C++ Cantera class “Func1”. See the Cantera C++ documentation for more details.

See also: polynom(), gaussian(), plus(), rdivide(), times()

Parameters:
  • typ –

    String indicating type of functor to create. Possible values are:

    • 'polynomial'
    • 'fourier'
    • 'gaussian'
    • 'arrhenius'
    • 'sum'
    • 'diff'
    • 'ratio'
    • 'composite'
    • 'periodic'
  • n – Number of parameters required for the functor
  • p – Vector of parameters
Returns:

Instance of class Func()
char(p)

Get the formatted string to display the function.

Parameters:p – Instance of class Func()
Returns:Formatted string displaying the function
gaussian(peak, center, width)

Create a Gaussian Func() instance.

Parameters:
  • peak – The peak value
  • center – Value of x at which the peak is located
  • width – Full width at half-maximum. The value of the function at center +/- (width)/2 is one-half the peak value.
plus(a, b)

Get a functor representing the sum of two input functors.

Parameters:
  • a – Instance of class Func()
  • b – Instance of class Func()
Returns:

Instance of class Func()

PLUS - Return a functor representing the sum of two functors a and b.

polynom(coeffs)

Create a polynomial Func() instance.

The polynomial coefficients are specified by a vector [a0 a1 .... aN]. Examples:

polynom([-2 6 3])          %3x^2 + 6.0x - 2
polynom([1.0 -2.5 0 0 2])  %2x^4 - 2.5x + 1
Parameters:coeffs – Vector of polynomial coefficients
Returns:Instance of class Func()
rdivide(a, b)

Get a functor that is the ratio of the input functors.

Parameters:
  • a – Instance of class Func()
  • b – Instance of class Func()
Returns:

Instance of class Func()
times(a, b)

Create a functor that multiplies two other functors.

Parameters:
  • a – Instance of class Func()
  • b – Instance of class Func()
Returns:

Instance of class Func()

Reactor

class Reactor(contents, typ)

Reactor class constructor.

A Reactor() object simulates a perfectly-stirred reactor. It has a time-dependent state, and may be coupled to other reactors through flow lines or through walls that may expand or contract and/or conduct heat.

>> r1 = Reactor      % an empty reactor
>> r2 = Reactor(gas) % a reactor containing a phase

See also: Reservoir(), IdealGasReactor(), IdealGasConstPressureReactor(), ConstPressureReactor()

Parameters:
  • contents – Instance of class Solution() representing the contents of the reactor
  • typ –

    Integer, reactor type. Options are:

    1. Reservoir
    2. Reactor
    3. Flow Reactor
    4. Constant Pressure Reactor
    5. Ideal Gas Reactor
    6. Ideal Gas Constant Pressure Reactor
Returns:

Instance of class Reactor()
ConstPressureReactor(contents)

Create a constant pressure reactor object.

A ConstPressureReactor() is an instance of class Reactor() where the pressure is held constant. The volume is not a state variable, but instead takes on whatever value is consistent with holding the pressure constant. Examples:

r1 = ConstPressureReactor         % an empty reactor
r2 = ConstPressureReactor(contents)    % a reactor containing contents

See also: Reactor()

Parameters:contents – Cantera Solution() to be set as the contents of the reactor
Returns:Instance of class Reactor()
FlowReactor(contents)

Create a flow reactor object.

A reactor representing adiabatic plug flow in a constant-area duct. Examples:

r1 = FlowReactor         % an empty reactor
r2 = FlowReactor(gas)    % a reactor containing a gas

See also: Reactor()

Parameters:contents – Cantera Solution() to be set as the contents of the reactor
Returns:Instance of class Reactor()
IdealGasConstPressureReactor(contents)

Create a constant pressure reactor with an ideal gas.

An IdealGasConstPressureReactor is an instance of class Reactor where the pressure is held constant. The volume is not a state variable, but instead takes on whatever value is consistent with holding the pressure constant. Additionally, its governing equations are specialized for the ideal gas equation of state (and do not work correctly with other thermodynamic models). Examples:

  r1 = IdealGasConstPressureReactor      % an empty reactor
  r2 = IdealGasConstPressureReactor(gas) % a reactor containing a gas

See also: :mat:func:`Reactor`
Parameters:contents – Cantera Solution() to be set as the contents of the reactor
Returns:Instance of class Reactor()
IdealGasReactor(contents)

Create a reactor with an ideal gas.

An IdealGasReactor is an instance of class Reactor where the governing equations are specialized for the ideal gas equation of state (and do not work correctly with other thermodynamic models). Examples:

r1 = IdealGasReactor         % an empty reactor
r2 = IdealGasReactor(gas)    % a reactor containing a gas

See also: Reactor()

Parameters:contents – Cantera Solution() to be set as the contents of the reactor
Returns:Instance of class Reactor()
Reservoir(contents)

Create a Reservoir object.

A Reservoir() is an instance of class Reactor() configured so that its intensive state is constant in time. A reservoir may be thought of as infinite in extent, perfectly mixed, and non-reacting, so that fluid may be extracted or added without changing the composition or thermodynamic state. Note that even if the reaction mechanism associated with the fluid in the reactor defines reactions, they are disabled within reservoirs. Examples:

r1 = Reservoir         % an empty reservoir
r2 = Reservoir(gas)    % a reservoir containing a gas

See also: Reactor()

Parameters:contents – Cantera Solution() to be set as the contents of the reactor
Returns:Instance of class Reactor()
density(r)

Get the density of the reactor.

Parameters:r – Instance of class Reactor()
Returns:Density of the phase in the input. Units: kg/m**3
enthalpy_mass(r)

The specific enthalpy of the reactor.

See also: intEnergy_mass()

Parameters:r – Instance of class Reactor()
Returns:The specific enthalpy of the reactor contents at the end of the last call to advance() or step(). The enthalpy is retrieved from the solution vector. Units: J/kg
insert(r, gas)

Insert a solution or mixture into a reactor.

Parameters:
intEnergy_mass(r)

Get the specific internal energy.

See also: enthalpy_mass()

Parameters:r – Instance of class Reactor()
Returns:The specific internal energy of the reactor contents at the end of the last call to advance() or step(). The internal energy is retrieved from the solution vector. Units: J/kg
mass(r)

Get the mass of the reactor.

Parameters:r – Instance of class Reactor()
Returns:The mass of the reactor contents at the end of the last call to advance() or step(). The mass is retrieved from the solution vector. Units: kg
massFraction(r, species)

Get the mass fraction of a species.

Parameters:
  • r – Instance of class Reactor()
  • species – String or the one-based integer index of the species
Returns:

The mass fraction of the specifed species in the reactor at the end of the last call to advance() or step().
massFractions(r)

Get the mass fractions of the species.

Parameters:r – Instance of class Reactor()
Returns:The mass fractions of the reactor contents at the end of the last call to advance() or step().
pressure(r)

Get the pressure of the reactor.

Parameters:r – Instance of class Reactor()
Returns:The pressure of the reactor contents at the end of the last call to advance() or step(). Units: Pa
setChemistry(r, flag)

Enable or disable changing reactor composition by reactions.

If the chemistry is disabled, then the reactor composition is constant. The parameter should be the string 'on' to enable the species equations, or 'off' to disable it.

By default, Reactor objects are created with the species equations enabled if there are reactions present in the mechanism file, and disabled otherwise.

>> setChemistry(r, 'on');
>> setChemistry(r, 'off');
Parameters:
  • r – Instance of class Reactor()
  • flag – String, either 'on' or 'off' to enable and disable solving the energy equation, respectively
setEnergy(r, flag)

Enable or disable solving the energy equation.

If the energy equation is disabled, then the reactor temperature is constant. The parameter should be the string 'on' to enable the energy equation, or 'off' to disable it.

By default, Reactor objects are created with the energy equation enabled, so usually this method is only needed to disable the energy equation for isothermal simulations.

>> setEnergy(r, 'on');
>> setEnergy(r, 'off');
Parameters:
  • r – Instance of class Reactor()
  • flag – String, either 'on' or 'off' to enable and disable solving the energy equation, respectively
setInitialVolume(r, v0)

Set the initial reactor volume.

Parameters:
  • r – Instance of class Reactor()
  • v0 – Initial volume. Units: m**3
setKineticsMgr(r, k)

Set the kinetics manager.

This method is used internally during Reactor initialization, but is usually not called by users.

Parameters:
  • r – Instance of class Reactor()
  • k – Instance of class Kinetics(), or another object containing an instance of that class.
setMassFlowRate(r, mdot)

Set the mass flow rate.

Parameters:
  • r – Instance of class Reactor()
  • mdot – Mass flow rate. Units: kg/s
setThermoMgr(r, t)

Set the thermodynamics manager.

This method is used internally during Reactor initialization, but is usually not called by users.

Parameters:
  • r – Instance of class Reactor()
  • t – Instance of class ThermoPhase(), or another object containing an instance of that class.
temperature(r)

Get the temperature of the reactor.

Parameters:r – Instance of class Reactor()
Returns:The temperature of the reactor contents at the end of the last call to advance() or step(). Units: K
volume(r)

Get the volume of the reactor.

Parameters:r – Instance of class Reactor()
Returns:The volume of the reactor contents at the end of the last call to advance() or step(). Units: m**3

ReactorNet

class ReactorNet(reactors)

ReactorNet class constructor.

A ReactorNet() object is a container that holds one or more Reactor() objects in a network. ReactorNet() objects are used to simultaneously advance the state of one or more coupled reactors.

Example:

>> r1 = Reactor(gas1)
>> r2 = Reactor(gas2)
>> <... install walls, inlets, outlets, etc...>

>> reactor_network = ReactorNet({r1, r2})
>> advance(reactor_network, time)

See also: Reactor()

Parameters:reactors – A single instance of Reactor() or a cell array of instances of Reactor()
Returns:Instance of class ReactorNet()
addReactor(net, reactor)

Add a reactor to a network.

Parameters:
advance(n, tout)

Advance the state of the reactor network in time.

Method advance() integrates the system of ordinary differential equations that determine the rate of change of the volume, the mass of each species, and the total energy for each reactor. The integration is carried out from the current time to time tout. (Note tout is an absolute time, not a time interval.) The integrator may take many internal time steps before reaching tout.

for i in 1:10
   tout = 0.1*i
   advance(n, tout)
   ...
   <add output commands here>
   ...
end

See also: step()

Parameters:
  • n – Instance of class ReactorNet()
  • tout – End time of the integration. The solver may take many internal time steps to reach tout.
atol(r)

Get the absolute error tolerance.

Parameters:r – Instance of class ReactorNet()
Returns:Absolute error tolerance.
rtol(r)

Get the relative error tolerance.

Parameters:r – Instance of class ReactorNet()
Returns:Relative error tolerance.
setInitialTime(r, t)

Set the initial time of the integration.

If the time integration has already begun, this restarts the integrator using the current solution as the initial condition, setting the time to t.

Parameters:
  • r – Instance of class ReactorNet()
  • t – Time at which integration should be restarted, using the current state as the initial condition. Units: s
setMaxTimeStep(r, maxstep)

Set the maximum time step.

The integrator chooses a step size based on the desired error tolerances and the rate at which the solution is changing. In some cases, the solution changes very slowly at first, then very rapidly (ignition problems). In such cases, the integrator may choose a timestep that is too large, which leads to numerical problems later. Use this method to set an upper bound on the timestep.

Parameters:
  • r – Instance of class ReactorNet()
  • maxstep – Maximum time step
setTolerances(r, rtol, atol)

Set the error tolerances.

Parameters:
  • r – Instance of class ReactorNet()
  • rtol – Scalar relative error tolerance
  • atol – Scalar absolute error tolerance
step(r)

Take one internal time step.

The integrator used to integrate the ODEs (CVODE) takes variable-size steps, chosen so that a specified error tolerance is maintained. At times when the solution is rapidly changing, the time step becomes smaller to resolve the solution.

Method step() takes one internal time step and returns the network time after taking that step. This can be useful when it is desired to resolve a rapidly-changing solution.

This method can be used as follows:

t = 0.0
tout = 0.1
while t < tout
   t = step(r)
   ,,,
   <commands to save desired variables>
   ...
end

See also: advance()

Parameters:r – Instance of class ReactorNet()
Returns:Network time after the internal time step. Units: s
time(r)

Get the current value of the time.

Parameters:r – Instance of class ReactorNet()
Returns:Current time in the input ReactorNet. Units: s

FlowDevice

class FlowDevice(typ)

FlowDevice class constructor.

Base class for devices that allow flow between reactors. FlowDevice() objects are assumed to be adiabatic, non-reactive, and have negligible internal volume, so that they are internally always in steady-state even if the upstream and downstream reactors are not. The fluid enthalpy, chemical composition, and mass flow rate are constant across a FlowDevice(), and the pressure difference equals the difference in pressure between the upstream and downstream reactors.

See also: MassFlowController(), Valve()

Parameters:typ – Type of FlowDevice() to be created. typ=1 for MassFlowController() and typ=3 for Valve()
Returns:Instance of class FlowDevice()
MassFlowController(upstream, downstream)

Create a mass flow controller.

Creates an instance of class FlowDevice() configured to simulate a mass flow controller that maintains a constant mass flow rate independent of upstream or downstream conditions. If two reactor objects are supplied as arguments, the controller is installed between the two reactors. Otherwise, the install() method should be used to install the MassFlowController() between reactors.

see also: FlowDevice(), Valve()

Parameters:
  • upstream – Upstream Reactor() or Reservoir()
  • downstream – Downstream Reactor() or Reservoir()
Returns:

Instance of class FlowDevice()
Valve(upstream, downstream)

Create a valve.

Create an instance of class FlowDevice() configured to simulate a valve that produces a flow rate proportional to the pressure difference between the upstream and downstream reactors.

The mass flow rate [kg/s] is computed from the expression

\[\dot{m} = K(P_{upstream} - P_{downstream}) \]

as long as this produces a positive value. If this expression is negative, zero is returned. Therefore, the Valve() object acts as a check valve - flow is always from the upstream reactor to the downstream one. Note: as currently implemented, the Valve object does not model real valve characteristics - in particular, it does not model choked flow. The mass flow rate is always assumed to be linearly proportional to the pressure difference, no matter how large the pressure difference. THIS MAY CHANGE IN A FUTURE RELEASE.

see also: FlowDevice(), MassFlowController()

Parameters:
  • upstream – Upstream reactor or reservoir
  • downstream – Downstream Reactor or reservoir
Returns:

Instance of class FlowDevice()
install(f, upstream, downstream)

Install a flow device between reactors or reservoirs.

Parameters:
Returns:

Instance of class FlowDevice()
massFlowRate(f, time)

Get the mass flow rate at a given time.

Parameters:
Returns:

The mass flow rate through the FlowDevice() at the given time
setFunction(f, mf)

Set the mass flow rate with class Func().

See also: MassFlowController(), Func()

Parameters:
setMassFlowRate(f, mdot)

Set the mass flow rate to a constant value.

See also: MassFlowController()

Parameters:
setValveCoeff(f, k)

Set the valve coefficient \(K\).

The mass flow rate [kg/s] is computed from the expression

\[\dot{m} = K(P_{upstream} - P_{downstream}) \]

as long as this produces a positive value. If this expression is negative, zero is returned.

See also: Valve()

Parameters:
  • f – Instance of class Valve()
  • k – Value of the valve coefficient. Units: kg/Pa-s

Wall

class Wall(left, right, area, k, u, q, v)

Wall class constructor.

A Wall separates two reactors, or a reactor and a reservoir. A wall has a finite area, may conduct heat between the two reactors on either side, and may move like a piston.

Walls are stateless objects in Cantera, meaning that no differential equation is integrated to determine any wall property. Since it is the wall (piston) velocity that enters the energy equation, this means that it is the velocity, not the acceleration or displacement, that is specified. The wall velocity is computed from

\[v = K(P_{\rm left} - P_{\rm right}) + v_0(t), \]

where \(K\) is a non-negative constant, and \(v_0(t)\) is a specified function of time. The velocity is positive if the wall is moving to the right.

The heat flux through the wall is computed from

\[q = U(T_{\rm left} - T_{\rm right}) + q_0(t), \]

where \(U\) is the overall heat transfer coefficient for conduction/convection. The function \(q_0(t)\) is a specified function of time. The heat flux is positive when heat flows from the reactor on the left to the reactor on the right.

Note: all of the arguments are optional and can be activated after initial construction by using the various methods of the Wall() class. Any improperly specified arguments will generate warnings; these can be ignored if the intention was to not use a particular argument. Thus, the velocity of the wall can be set by using empty strings or 0.0 for each of the arguments before the velocity with no harm.

Parameters:
  • left – Instance of class Reactor() to be used as the bulk phase on the left side of the wall. See install()
  • right – Instance of class Reactor() to be used as the bulk phase on the right side of the wall. See install()
  • area – The area of the wall in m**2. See area() and setArea(). Defaults to 1.0 m**2 if not specified.
  • k – Expansion rate coefficient in m/(s-Pa). See setExpansionRateCoeff() and vdot(). Defaults to 0.0 if not specified.
  • u – Heat transfer coefficient in W/(m**2-K). See setHeatTransferCoeff() and qdot(). Defaults to 0.0 if not specified.
  • q – Heat flux in W/m**2. Must be an instance of Func(). See setHeatFlux() and qdot(). Defaults to 0.0 if not specified.
  • v – Velocity of the wall in m/s. Must be an instance of Func(). See setVelocity() and vdot(). Defaults to 0.0 if not specified.
Returns:

Instance of class Wall()
area(w)

Get the area of the wall.

Parameters:w – Instance of class Wall()
Returns:Area of the wall in m**2
install(w, left, right)

Install a wall between two reactors.

Parameters:
  • w – Instance of class Wall()
  • left – Instance of class Reactor`or :mat:func:`Reservoir()
  • right – Instance of class Reactor() or Reservoir()
qdot(w, t)

Get the total heat transfer through a wall given a time.

A positive value corresponds to heat flowing from the left-hand reactor to the right-hand one.

Parameters:
  • w – Instance of class Wall()
  • t – Time at which the heat transfer should be evaluated.
Returns:

Total heat transfer. Units: W
ready(w)

Check whether a wall is ready.

Parameters:w – Instance of class Wall()
Returns:Status of the wall
setArea(w, a)

Set the area of a wall.

Parameters:
  • w – Instance of class Wall()
  • a – Double area of the wall.
setExpansionRateCoeff(w, k)

Set the expansion rate coefficient.

The expansion rate coefficient determines the velocity of the wall for a given pressure differential between the left and right reactors, according to the formula

\[v = K(P_{left}-P_{right}) \]

where \(v\) is velocity, \(K\) is the expansion rate coefficient, and \(P\) is the pressure.

Parameters:
  • w – Instance of class Wall()
  • k – Double, wall expansion rate coefficient. Units: m/(s-Pa)
setHeatFlux(w, f)

Set the heat flux using Func()

Must be set by an instance of class Func(), which allows the heat flux to be an arbitrary function of time. It is possible to specify a constant heat flux by using the polynomial functor with only the first term specified:

w = Wall()
f = Func('polynomial',0,10); % Or f = polynom(10);
setHeatFlux(w, f);

sets the heat flux through the wall to 10 W/m**2.

Parameters:
  • w – Instance of class Wall()
  • f – Instance of class Func(). Units: W/m**2
setHeatTransferCoeff(w, u)

Set the heat transfer coefficient.

Parameters:
  • w – Instance of class Wall()
  • u – Heat transfer coefficient of the wall. Units: W/(m**2-K)
setThermalResistance(w, r)

Set the thermal resistance.

Parameters:
  • w – Instance of class Wall()
  • r – Double, thermal resistance. Units: K*m**2/W
setVelocity(w, f)

Set the velocity of the wall using Func().

Must be set by an instance of class Func(), which allows the velocity to be an arbitrary function of time. It is possible to specify a constant velocity by using the polynomial functor with only the first term specified:

w = Wall()
f = Func('polynomial',0,10); % Or f = polynom(10);
setVelocity(w, f);

sets the velocity of the wall to 10 m/s.

Parameters:
  • w – Instance of class Wall()
  • f – Instance of class Func(). Units: m/s
vdot(w, t)

Get the rate of volumetric change at a given time.

A positive value corresponds to the left-hand reactor volume increasing, and the right-hand reactor volume decreasing.

Parameters:
  • w – Instance of class Wall()
  • t – Time at which the volumetric change should be calculated.
Returns:

Rate of volumetric change Units: m**3/s