diff --git a/doc/sphinx/cti/phases.rst b/doc/sphinx/cti/phases.rst index cb623dc8b..d0250e246 100644 --- a/doc/sphinx/cti/phases.rst +++ b/doc/sphinx/cti/phases.rst @@ -429,6 +429,8 @@ A stoichiometric liquid differs from a stoichiometric solid in only one respect: the transport manager computes the viscosity as well as the thermal conductivity. +.. _sec-interfaces: + Interfaces ========== diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/Domain1D.m b/interfaces/matlab/toolbox/1D/@Domain1D/Domain1D.m index 3800e0d2a..62191d59f 100755 --- a/interfaces/matlab/toolbox/1D/@Domain1D/Domain1D.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/Domain1D.m @@ -1,6 +1,28 @@ function d = Domain1D(a, b, c) -% DOMAIN1D - Create a new one-dimensional domain. +% DOMAIN1D Domain1D class constructor. +% d = Domain1D(a, b, c) +% :param a: +% Integer type of domain. Possible values are % +% * 1 - Stagnation Flow +% * 2 - Inlet1D +% * 3 - Surf1D +% * 4 - Symm1D +% * 5 - Outlet1D +% * 6 - Reacting Surface +% * 8 - Sim1D +% * -2 - OutletRes +% +% :param b: +% Instance of class :mat:func:`Solution` (for ``a == 1``) +% or :mat:func:`Interface` (for ``a == 6``). Not used for +% all other valid values of ``a``. +% :param c: +% Integer, either 1 or 2, indicating whether an axisymmetric +% stagnation flow or a free flame should be created. If not +% specified, defaults to 1. Ignored if ``a != 1``. +% + d.dom_id = -1; % Valid job numbers for one argument diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/componentIndex.m b/interfaces/matlab/toolbox/1D/@Domain1D/componentIndex.m index 543e76693..33b4e03d2 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/componentIndex.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/componentIndex.m @@ -1,5 +1,13 @@ function n = componentIndex(d, name) -% COMPONENTINDEX - +% COMPONENTINDEX Get the index of a component given its name. +% n = componentIndex(d, name) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param name: +% String name of the component to look up. If a numeric value +% is passed, it will be returned. +% :return: +% Index of the component, or input numeric value. % if isa(name, 'double') diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/componentName.m b/interfaces/matlab/toolbox/1D/@Domain1D/componentName.m index 8493ca566..c558a48fe 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/componentName.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/componentName.m @@ -1,6 +1,15 @@ function s = componentName(d, n) -% COMPONENTNAME - Name of component n. +% COMPONENTNAME Get the name of a component given its index. +% s = componentName(d, n) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param n: +% Integer or vector of integers of components' names +% to get. +% :return: +% Cell array of component names. % + m = length(n); s = cell(m); for i = 1:m diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/disableEnergy.m b/interfaces/matlab/toolbox/1D/@Domain1D/disableEnergy.m index 708e258b8..7ba64a8b0 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/disableEnergy.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/disableEnergy.m @@ -1,4 +1,11 @@ function d = disableEnergy(d) -% ENABLEENERGY - enable the energy equation +% DISABLEENERGY Disable the energy equation. +% d = disableEnergy(d) +% :param d: +% Instance of class :mat:func:`Domain1D` % + +disp(' '); +disp('Disabling the energy equation...'); + domain_methods(d.dom_id, 66, 0); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/domainIndex.m b/interfaces/matlab/toolbox/1D/@Domain1D/domainIndex.m index 0b5892064..bb5144301 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/domainIndex.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/domainIndex.m @@ -1,8 +1,12 @@ function i = domainIndex(d) -% DOMAININDEX - domain index. -% +% DOMAININDEX Get the domain index. +% i = domainIndex(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: % This function returns an integer flag denoting the location % of the domain, beginning with 1 at the left. % + i = domain_methods(d.dom_id, 13) + 1; diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/domainType.m b/interfaces/matlab/toolbox/1D/@Domain1D/domainType.m index 48e35ddc9..156c7d63c 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/domainType.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/domainType.m @@ -1,7 +1,12 @@ function i = domainType(d) -% DOMAINTYPE - Type of domain. -% +% DOMAINTYPE Get the type of domain. +% i = domainType(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: % This function returns an integer flag denoting the domain % type. +% + i = domain_methods(d.dom_id, 12); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/domain_hndl.m b/interfaces/matlab/toolbox/1D/@Domain1D/domain_hndl.m index 4632d3545..11c0c79a2 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/domain_hndl.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/domain_hndl.m @@ -1,5 +1,12 @@ function n = domain_hndl(d) -% DOMAIN_HNDL - Integer used to access kernel object. +% DOMAIN_HNDL Get the integer used to access the kernel object. +% n = domain_hndl(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% for which the handle is desired. +% :return: +% Integer used to access the kernel object % + n = d.dom_id; diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/enableEnergy.m b/interfaces/matlab/toolbox/1D/@Domain1D/enableEnergy.m index d8e93f6b2..ec533af4a 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/enableEnergy.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/enableEnergy.m @@ -1,6 +1,10 @@ function d = enableEnergy(d) -% ENABLEENERGY - enable the energy equation +% ENABLEENERGY Enable the energy equation. +% d = enableEnergy(d) +% :param d: +% Instance of class :mat:func:`Domain1D` % + disp(' '); disp('Enabling the energy equation...'); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/gridPoints.m b/interfaces/matlab/toolbox/1D/@Domain1D/gridPoints.m index 756542688..746429411 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/gridPoints.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/gridPoints.m @@ -1,6 +1,14 @@ function zz = gridPoints(d, n) -% GRID - +% GRIDPOINTS Get grid points from a domain. +% zz = gridPoints(d, n) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param n: +% Optional, vector of grid points to be retrieved. +% :return: +% Vector of grid points. Length of ``n`` or :mat:func:`nPoints`. % + if nargin == 1 zz = zeros(1, nPoints(d)); for i = 1:nPoints(d) diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/isFlow.m b/interfaces/matlab/toolbox/1D/@Domain1D/isFlow.m index 2aa39a211..e359f1312 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/isFlow.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/isFlow.m @@ -1,6 +1,12 @@ function a = isFlow(d) -% ISFLOW - Returns 1 if the domain is a flow domain, and 0 otherwise. +% ISFLOW Determine whether a domain is a flow. +% a = isFlow(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: +% 1 if the domain is a flow domain, and 0 otherwise. % + t = domainType(d); if t == 50 a = 1; diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/isInlet.m b/interfaces/matlab/toolbox/1D/@Domain1D/isInlet.m index 664e88730..b552004bc 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/isInlet.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/isInlet.m @@ -1,6 +1,12 @@ function a = isInlet(d) -% ISINLET - Returns 1 if the domain is an inlet, and 0 otherwise. -% +% ISINLET Determine whether a domain is an inlet. +% a = isInlet(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: +% 1 if the domain is an inlet, and 0 otherwise. +% + t = domainType(d); if t == 104 a = 1; diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/isSurface.m b/interfaces/matlab/toolbox/1D/@Domain1D/isSurface.m index df3fc8c53..aa43846f4 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/isSurface.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/isSurface.m @@ -1,6 +1,12 @@ function a = isSurface(d) -% ISSURFACE - Returns 1 if the domain is a surface, and 0 otherwise. +% ISSURFACE Determine if a domain is a surface. +% a = isSurface(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: +% 1 if the domain is a surface, and 0 otherwise. % + t = domainType(d); if t == 102 a = 1; diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/massFlux.m b/interfaces/matlab/toolbox/1D/@Domain1D/massFlux.m index 58f06674d..a8a87348e 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/massFlux.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/massFlux.m @@ -1,4 +1,10 @@ function mdot = massFlux(d) -% MASSFLUX - +% MASSFLUX Get the mass flux. +% mdot = massFlux(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: +% The mass flux in the domain. % + mdot = domain_methods(d.dom_id, 17); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/massFraction.m b/interfaces/matlab/toolbox/1D/@Domain1D/massFraction.m index 70f71225a..4fdce45e5 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/massFraction.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/massFraction.m @@ -1,9 +1,16 @@ function y = massFraction(d, k) -% MASSFRACTION - Mass fraction of species k. +% MASSFRACTION Get the mass fraction of a species given its integer index. +% y = massFraction(d, k) +% This method returns the mass fraction of species ``k``, where +% k is the integer index of the species in the flow domain +% to which the boundary domain is attached. % -% This method returns the mass fraction of species k, where -% k is the integer index of the species in the flow domain -% to which the boundary domain is attached. +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param k: +% Integer species index +% :return: +% Mass fraction of species % if domainIndex(d) == 0 diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/nComponents.m b/interfaces/matlab/toolbox/1D/@Domain1D/nComponents.m index bc46e423a..05de09589 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/nComponents.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/nComponents.m @@ -1,4 +1,10 @@ function n = nComponents(d) -% NCOMPONENTS - number of components +% NCOMPONENTS Get the number of components. +% n = nComponents(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: +% Number of variables at each grid point % + n = domain_methods(d.dom_id, 11); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/nPoints.m b/interfaces/matlab/toolbox/1D/@Domain1D/nPoints.m index 489c4f940..66aeb5832 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/nPoints.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/nPoints.m @@ -1,4 +1,10 @@ function npts = nPoints(d) -% NPOINTS - Number of grid points. -% +% NPOINTS Get the number of grid points. +% npts = nPoints(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: +% Integer number of grid points. +% + npts = domain_methods(d.dom_id, 14); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/set.m b/interfaces/matlab/toolbox/1D/@Domain1D/set.m index bc984e093..98a77786d 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/set.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/set.m @@ -1,27 +1,43 @@ function a = set(a,varargin) -% SET - Set properties. +% SET Set properties of a Domain1D. +% a = set(a,varargin) +% The properties that may be set are % -% The properties that may be set are +% * Temperature (T) +% * Pressure (P) +% * Mole Fractions (X) +% * Mass Flux (mdot) +% * tol +% * tol-time +% * grid +% * bounds +% * T_fixed +% * ID % -% Either the full property name or the symbol may be -% specified. For the extensive properties (V,H,U,S), the values -% must be given per unit mass. H, U, and S must be set in -% conjunction with pressure (for H,S) or volume (for U,S). Either -% (specific) volume or density may be specified. Mole and mass -% fractions must be input as vectors (either row or column) with -% length equal to the number of species. +% Either the full property name or the symbol may be +% specified. Mole and mass +% fractions must be input as vectors (either row or column) with +% length equal to the number of species. % -% Examples: +% Examples:: % -% set(gas,'Temperature',600.0); -% set(gas,'T',600.0); -% set(gas,'T',600.0,'P',2*oneatm,'Y',massfracs); -% set(gas,'H',0.5*enthalpy_mass(gas),'P',pressure(gas)); -% set(gas,'S',entropy_mass(gas),'P',0.5*pressure(gas)); -% set(gas,'X',ones(nSpecies(gas),1)); +% >> set(gas,'Temperature',600.0); +% >> set(gas,'T',600.0); +% >> set(gas,'T',600.0,'P',2*oneatm,'Y',massfracs); +% >> set(gas,'X',ones(nSpecies(gas),1)); % -% Alternatively, individual methods to set properties may be -% called (setTemperature, setMoleFractions, etc.) +% Alternatively, individual methods to set properties may be +% called (setTemperature, setMoleFractions, etc.) +% +% See also: :mat:func:`setBounds`, :mat:func:`setFixedTempProfile` :mat:func:`setID`, +% :mat:func:`setMdot`, :mat:func:`setMoleFractions`, :mat:func:`setPressure`, +% :mat:func:`setProfile`, :mat:func:`setSteadyTolerances`, :mat:func:`setTemperature`, +% :mat:func:`setTransientTolerances`, :mat:func:`setupGrid` +% +% :param a: +% Instance of class :mat:func:`Domain1D` +% :param varargin: +% Comma separated list of ``property, value`` pairs to be set % property_argin = varargin; diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setBounds.m b/interfaces/matlab/toolbox/1D/@Domain1D/setBounds.m index 04ddc1f82..c789c6d9e 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setBounds.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setBounds.m @@ -1,5 +1,14 @@ function setBounds(d, component, lower, upper) -% SETBOUNDS - +% SETBOUNDS Set bounds on the solution components. +% d = setBounds(d, component, lower, upper) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param component: +% String, component to set the bounds on +% :param lower: +% Lower bound +% :param upper: +% Upper bound % n = componentIndex(d, component); domain_methods(d.dom_id, 51, n, lower, upper); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setCoverageEqs.m b/interfaces/matlab/toolbox/1D/@Domain1D/setCoverageEqs.m index 849345d16..218070dd9 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setCoverageEqs.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setCoverageEqs.m @@ -1,6 +1,14 @@ function setCoverageEqs(d, onoff) -% SETCOVERAGEEQS - Enable or disable solving the coverage equations. +% SETCOVERAGEEQS Enable or disable solving the coverage equations. +% d = setCoverageEqs(d,onoff) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param onoff: +% String, one of ``'on'`` or ``'yes'`` to turn solving +% the coverage equations on. One of ``'off'`` or ``'no'`` +% to turn off the coverage equations. % + if d.domain_type ~= 6 error('Wrong domain type. Expected a reacting surface domain.') end diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setFixedTempProfile.m b/interfaces/matlab/toolbox/1D/@Domain1D/setFixedTempProfile.m index 9b8385905..9772dede6 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setFixedTempProfile.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setFixedTempProfile.m @@ -1,9 +1,18 @@ function setFixedTempProfile(d, profile) -% SETFIXEDTEMPPROFILE - set the temperature profile to use when the +% SETFIXEDTEMPPROFILE Set a fixed temperature profile. +% d = setFixedTempProfile(d, profile) +% Set the temperature profile to use when the % energy equation is not being solved. The profile must be entered % as an array of positions / temperatures, which may be in rows or -% columns. -% +% columns. +% +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param profile: +% n x 2 or 2 x n array of ``n`` points at which the temperature +% is specified. +% + sz = size(profile); if sz(1) == 2 domain_methods(d.dom_id, 64, profile(1,:), profile(2,:)); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setID.m b/interfaces/matlab/toolbox/1D/@Domain1D/setID.m index 7f8300819..227829819 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setID.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setID.m @@ -1,4 +1,10 @@ function setID(d, id) -% SETID - Set the ID tag for the domain. +% SETID Set the ID tag for a domain. +% d = setID(d, id) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param id: +% String ID to assign % + domain_methods(d.dom_id, 54, id); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setMdot.m b/interfaces/matlab/toolbox/1D/@Domain1D/setMdot.m index b951bf2f4..a857da407 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setMdot.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setMdot.m @@ -1,4 +1,10 @@ function setMdot(d, mdot) -% SETMDOT - +% SETMDOT Set the mass flow rate. +% d = setMdot(d, mdot) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param mdot: +% Mass flow rate % + domain_methods(d.dom_id, 60, mdot); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setMoleFractions.m b/interfaces/matlab/toolbox/1D/@Domain1D/setMoleFractions.m index 6536c92e1..a40a7d311 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setMoleFractions.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setMoleFractions.m @@ -1,4 +1,11 @@ function setMoleFractions(d, x) -% SETMOLEFRACTIONS - +% SETMOLEFRACTIONS Set the mole fractions. +% d = setMoleFractions(d, x) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param x: +% String specifying the species and mole fractions in +% the format ``'SPEC:X,SPEC2:X2'``. % + domain_methods(d.dom_id, 62, x); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setPressure.m b/interfaces/matlab/toolbox/1D/@Domain1D/setPressure.m index f96ffad8b..b84c758a9 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setPressure.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setPressure.m @@ -1,4 +1,10 @@ function setPressure(d, p) -% SETPRESSURE - +% SETPRESSURE Set the pressure. +% d = setPressure(d, p) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param p: +% Pressure to be set. Units: Pa % + domain_methods(d.dom_id, 63, p); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setProfile.m b/interfaces/matlab/toolbox/1D/@Domain1D/setProfile.m index 9087ac1bc..1d2008675 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setProfile.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setProfile.m @@ -1,6 +1,20 @@ function setProfile(d, n, p) -% SETPROFILE - +% SETPROFILE Set the profile of a component. +% d = setProfile(d, n, p) +% Convenience function to allow an instance of :mat:func:`Domain1D` to +% have a profile of its components set when it is part of a :mat:func:`Stack`. % +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param n: +% Integer index of component, vector of component indices, string +% of component name, or cell array of strings of component names. +% :param p: +% n x 2 array, whose columns are the relative (normalized) positions +% and the component values at those points. The number of positions +% ``n`` is arbitrary. +% + if d.stack == 0 error('Install domain in stack before calling setProfile.'); end diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setSteadyTolerances.m b/interfaces/matlab/toolbox/1D/@Domain1D/setSteadyTolerances.m index 8640aa891..7d61d3ab0 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setSteadyTolerances.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setSteadyTolerances.m @@ -1,5 +1,16 @@ function setSteadyTolerances(d, component, rtol, atol) -% SETSTEADYTOLERANCES - +% SETSTEADYTOLERANCES Set the steady-state tolerances. +% d = setSteadyTolerances(d, component, rtol, atol) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param component: +% String or cell array of strings of component values +% whose tolerances should be set. If ``'default'`` is +% specified, the tolerance of all components will be set. +% :param rtol: +% Relative tolerance +% :param atol: +% Absolute tolerance % if strcmp(component, 'default') diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setTemperature.m b/interfaces/matlab/toolbox/1D/@Domain1D/setTemperature.m index 5263b5184..536942c9c 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setTemperature.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setTemperature.m @@ -1,4 +1,10 @@ function setTemperature(d, t) -% SETTEMPERATURE - Set the temperature [K]. +% SETTEMPERATURE Set the temperature. +% d = setTemperature(d, t) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param t: +% Temperature to be set. Units: K % + domain_methods(d.dom_id, 61, t); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setTransientTolerances.m b/interfaces/matlab/toolbox/1D/@Domain1D/setTransientTolerances.m index 89a2c7c8a..7f6977938 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setTransientTolerances.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setTransientTolerances.m @@ -1,5 +1,16 @@ function setTransientTolerances(d, component, rtol, atol) -% SETSTEADYTOLERANCES - +% SETTRANSIENTTOLERANCES Set the transient tolerances. +% d = setTransientTolerances(d, component, rtol, atol) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param component: +% String or cell array of strings of component values +% whose tolerances should be set. If ``'default'`` is +% specified, the tolerance of all components will be set. +% :param rtol: +% Relative tolerance +% :param atol: +% Absolute tolerance % if strcmp(component, 'default') diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/setupGrid.m b/interfaces/matlab/toolbox/1D/@Domain1D/setupGrid.m index de65e2409..1474cc790 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/setupGrid.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/setupGrid.m @@ -1,4 +1,9 @@ function setupGrid(d, grid) -% SETUPGRID - +% SETUPGRID Set up the solution grid. +% d = setupGrid(d, grid) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param grid: % + domain_methods(d.dom_id, 53, grid); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/temperature.m b/interfaces/matlab/toolbox/1D/@Domain1D/temperature.m index 284e78d4e..394443d35 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/temperature.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/temperature.m @@ -1,4 +1,10 @@ function t = temperature(d) -% TEMPERATURE - Temperature [K]. +% TEMPERATURE Get the boundary temperature. +% t = temperature(d) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :return: +% Temperature. Units: K % + t = domain_methods(d.dom_id, 15); diff --git a/interfaces/matlab/toolbox/1D/@Domain1D/z.m b/interfaces/matlab/toolbox/1D/@Domain1D/z.m index 4d9c5cdc4..65ff6a58e 100644 --- a/interfaces/matlab/toolbox/1D/@Domain1D/z.m +++ b/interfaces/matlab/toolbox/1D/@Domain1D/z.m @@ -1,6 +1,15 @@ function zz = z(d, n) -% GRID - +% Z Get the grid points. +% zz = z(d, n) +% :param d: +% Instance of class :mat:func:`Domain1D` +% :param n: +% Optional. Indices of grid points to get. +% Defaults to getting all of the grid points. +% :return: +% Vector of grid points. % + if nargin == 1 zz = zeros(1, nPoints(d)); for i = 1:nPoints(d) diff --git a/interfaces/matlab/toolbox/1D/@Stack/Stack.m b/interfaces/matlab/toolbox/1D/@Stack/Stack.m index ef9f0ffd4..412d8d9df 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/Stack.m +++ b/interfaces/matlab/toolbox/1D/@Stack/Stack.m @@ -1,11 +1,18 @@ function s = Stack(domains) +% STACK Stack class constructor. +% s = Stack(domains) +% A stack object is a container for one-dimensional domains, +% which are instances of class Domain1D. The domains are of two +% types - extended domains, and connector domains. % -% STACK - A one-dimensional 'stack' of domains. +% See also: :mat:func:`Domain1D` % -% A stack object is a container for one-dimensional domains, -% which are instances of class Domain1D. The domains are of two -% types - extended domains, and connector domains. +% :param domains: +% Vector of domain instances +% :return: +% Instance of class :mat:func:`Stack` % + s.stack_id = -1; s.domains = domains; if nargin == 1 diff --git a/interfaces/matlab/toolbox/1D/@Stack/display.m b/interfaces/matlab/toolbox/1D/@Stack/display.m index 6fea51b15..36048017f 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/display.m +++ b/interfaces/matlab/toolbox/1D/@Stack/display.m @@ -1,8 +1,12 @@ function display(s, fname) -% DISPLAY - show all domains. -% -% fname - file to write summary to. If omitted, output is to the screen. +% DISPLAY Show all domains. +% display(s, fname) +% :param s: +% Instance of class :mat:func:`Stack` +% :param fname: +% File to write summary to. If omitted, output is to the screen. % + if nargin == 1 fname = '-'; end diff --git a/interfaces/matlab/toolbox/1D/@Stack/domainIndex.m b/interfaces/matlab/toolbox/1D/@Stack/domainIndex.m index b5c73caaf..e9cd0df61 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/domainIndex.m +++ b/interfaces/matlab/toolbox/1D/@Stack/domainIndex.m @@ -1,5 +1,14 @@ function n = domainIndex(s, name) -% DOMAININDEX - Index of the domain with a specified name. +% DOMAININDEX Get the index of a domain in a stack given its name. +% n = domainIndex(s, name) +% :param s: +% Instance of class :mat:func:`Stack` +% :param name: +% If double, the value is returned. Otherwise, +% the name is looked up and its index is returned. +% :return: +% Index of domain +% if isa(name, 'double') n = name; diff --git a/interfaces/matlab/toolbox/1D/@Stack/grid.m b/interfaces/matlab/toolbox/1D/@Stack/grid.m index d498ec718..02fa048a6 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/grid.m +++ b/interfaces/matlab/toolbox/1D/@Stack/grid.m @@ -1,5 +1,13 @@ function z = grid(s, name) -% GRID - the grid in one domain. +% GRID Get the grid in one domain. +% z = grid(s, name) +% :param s: +% Instance of class :mat:func:`Stack` +% :param name: +% Name of the domain for which the grid +% should be retrieved. +% :return: +% The grid in domain name % n = domainIndex(s, name); diff --git a/interfaces/matlab/toolbox/1D/@Stack/plotSolution.m b/interfaces/matlab/toolbox/1D/@Stack/plotSolution.m index a80d671b4..fff0f048f 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/plotSolution.m +++ b/interfaces/matlab/toolbox/1D/@Stack/plotSolution.m @@ -1,7 +1,13 @@ function plotSolution(s, domain, component) -% PLOTSOLUTION - plot a specified solution component -% -% plotSolution(s, 'flow', 'T') plots component 'T' in domain 'flow' +% PLOTSOLUTION Plot a specified solution component. +% plotSolution(s, domain, component) +% :param s: +% Instance of class :mat:func:`Stack` +% :param domain: +% Name of domain from which the component should be +% retrieved +% :param component: +% Name of the component to be plotted % n = domainIndex(s, domain); diff --git a/interfaces/matlab/toolbox/1D/@Stack/resid.m b/interfaces/matlab/toolbox/1D/@Stack/resid.m index 1707dc2b7..01ae0c370 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/resid.m +++ b/interfaces/matlab/toolbox/1D/@Stack/resid.m @@ -1,4 +1,15 @@ function r = resid(s, domain, rdt, count) +% RESID Get the residuals. +% r = resid(s, domain, rdt, count) +% :param s: +% Instance of class :mat:func:`Stack` +% :param domain: +% Name of the domain +% :param rdt: +% :param count: +% :returns: +% + if nargin == 2 rdt = 0.0; count = 0; diff --git a/interfaces/matlab/toolbox/1D/@Stack/restore.m b/interfaces/matlab/toolbox/1D/@Stack/restore.m index e9349259e..04ffc0f76 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/restore.m +++ b/interfaces/matlab/toolbox/1D/@Stack/restore.m @@ -1,6 +1,16 @@ function restore(s, fname, id) -% RESTORE - Restore a previously-saved solution. +% RESTORE Restore a previously-saved solution. +% restore(s, fname, id) +% This method can be used to provide an initial guess for the solution. % -% This method can be used to provide an initial guess for the -% solution. +% See also: :mat:func:`save` +% +% :param s: +% Instance of class :mat:func:`Stack` +% :param fname: +% File name of an XML file containing solution information +% :param id: +% ID of the element that should be restored +% + stack_methods(s.stack_id, 111, fname, id); diff --git a/interfaces/matlab/toolbox/1D/@Stack/save.m b/interfaces/matlab/toolbox/1D/@Stack/save.m index bf49d0a6e..2fc88dc20 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/save.m +++ b/interfaces/matlab/toolbox/1D/@Stack/save.m @@ -1,6 +1,20 @@ function save(s, fname, id, desc) -% SAVE - +% SAVE Save a solution to a file. +% save(s, fname, id, desc) +% The output file is in a format that +% can be used by :mat:func:`restore` % +% :param s: +% Instance of class :mat:func:`Stack` +% :param fname: +% File name where XML file should be written +% :param id: +% ID to be assigned to the XML element when it is +% written +% :param desc: +% Description to be written to the output file +% + if nargin == 2 id = 'solution'; desc = '-'; diff --git a/interfaces/matlab/toolbox/1D/@Stack/saveSoln.m b/interfaces/matlab/toolbox/1D/@Stack/saveSoln.m index c9c3d417e..27407a20f 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/saveSoln.m +++ b/interfaces/matlab/toolbox/1D/@Stack/saveSoln.m @@ -1,6 +1,20 @@ function saveSoln(s, fname, id, desc) -% SAVE - Save solution. +% SAVESOLN Save a solution to a file. +% saveSoln(s, fname, id, desc) +% The output file is in a format that +% can be used by :mat:func:`restore` % +% :param s: +% Instance of class :mat:func:`Stack` +% :param fname: +% File name where XML file should be written +% :param id: +% ID to be assigned to the XML element when it is +% written +% :param desc: +% Description to be written to the output file +% + if nargin == 1 fname = 'soln.xml'; id = 'solution'; diff --git a/interfaces/matlab/toolbox/1D/@Stack/setFlatProfile.m b/interfaces/matlab/toolbox/1D/@Stack/setFlatProfile.m index 5ea685706..52e46dcb2 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/setFlatProfile.m +++ b/interfaces/matlab/toolbox/1D/@Stack/setFlatProfile.m @@ -1,5 +1,14 @@ function setFlatProfile(s, domain, comp, v) -% SETFLATPROFILE - +% SETFLATPROFILE Set a component to a value across the entire domain. +% setFlatProfile(s, domain, comp, v) +% :param s: +% Instance of class :mat:func:`Stack` +% :param domain: +% Integer ID of the domain +% :param comp: +% Component to be set +% :param v: +% Double, value to be set % stack_methods(s.stack_id, 102, domain, comp, v); diff --git a/interfaces/matlab/toolbox/1D/@Stack/setMaxJacAge.m b/interfaces/matlab/toolbox/1D/@Stack/setMaxJacAge.m index 5e3148a8b..590434026 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/setMaxJacAge.m +++ b/interfaces/matlab/toolbox/1D/@Stack/setMaxJacAge.m @@ -1,7 +1,15 @@ function setMaxJacAge(s, ss_age, ts_age) -% SETMAXJACAGE - Set the number of times the Jacobian will be used -% before it is recomputed. +% SETMAXJACAGE Set the number of times the Jacobian will be used before it is recomputed. +% setMaxJacAge(s, ss_age, ts_age) +% :param s: +% Instance of class :mat:func:`Stack` +% :param ss_age: +% Maximum age of the Jacobian for steady state analysis +% :param ts_age: +% Maximum age of the Jacobian for transient analysis. If +% not specified, defaults to ``ss_age``. % + if nargin == 2 ts_age = ss_age; end diff --git a/interfaces/matlab/toolbox/1D/@Stack/setProfile.m b/interfaces/matlab/toolbox/1D/@Stack/setProfile.m index b60fab569..533fe4b7b 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/setProfile.m +++ b/interfaces/matlab/toolbox/1D/@Stack/setProfile.m @@ -1,23 +1,29 @@ function setProfile(s, name, comp, p) -% SETPROFILE - Specify a profile for one component. +% SETPROFILE Specify a profile for one component. +% setProfile(s, name, comp, p) +% The solution vector values for this component will be linearly +% interpolated from the discrete function defined by p(:,1) vs. p(:,2). +% Note that ``p(1,1) = 0.0`` corresponds to the leftmost grid point in +% the specified domain, and ``p(1,n) = 1.0`` corresponds to the rightmost +% grid point. This method can be called at any time, but is +% usually used to set the initial guess for the solution. % -% name -- domain name -% comp -- component number -% zr -- array of relative positions (0.0 to 1.0) -% v -- array of values +% Example (assuming ``s`` is an instance of :mat:func:`Stack`):: % -% The solution vector values for this component will be linearly -% interpolated from the discrete function defined by v vs. zr. -% Note that zr = 0.0 corresponds to the leftmost grid point in -% the specified domain, and zr = 1.0 corresponds to the rightmost -% grid point. This method can be called at any time, but is -% usually used to set the initial guess for the solution. +% >> zr = [0 0.1 0.2 0.4 0.8 1]; +% >> v = [500 650 700 730 800 900]; +% >> setProfile(s, 1, 2, [zr, v]); % -% Example: -% -% zr = [0 0.1 0.2 0.4 0.8 1]; -% v = [500 650 700 730 800 900]; -% setProfile(1, 2, zr, v); +% :param s: +% Instance of class :mat:func:`Stack` +% :param name: +% Domain name +% :param comp: +% component number +% :param p: +% n x 2 array, whose columns are the relative (normalized) positions +% and the component values at those points. The number of positions +% ``n`` is arbitrary. % if isa(name, 'double') diff --git a/interfaces/matlab/toolbox/1D/@Stack/setRefineCriteria.m b/interfaces/matlab/toolbox/1D/@Stack/setRefineCriteria.m index ed6bd5740..c24391173 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/setRefineCriteria.m +++ b/interfaces/matlab/toolbox/1D/@Stack/setRefineCriteria.m @@ -1,17 +1,24 @@ function setRefineCriteria(s, n, ratio, slope, curve, prune) -% SETREFINECRITERIA - Set the criteria used to refine the grid. -% -% n -- domain number beginning with domain 1 at the left -% ratio -- maximum size ratio between adjacent cells -% slope -- maximum relative difference in value between -% adjacent points -% curve -- maximum relative difference in slope between -% adjacent cells -% prune -- minimum value for slope or curve for which points -% will be retained in the grid. If the computed -% slope or curve value is below prune for all -% components, it will be deleted, unless either -% neighboring point is already marked for deletion. +% SETREFINECRITERIA Set the criteria used to refine the grid. +% s = setRefineCriteria(s, n, ratio, slope, curve, prune) +% :param s: +% Instance of class :mat:func:`Stack` +% :param n: +% Domain number +% :param ratio: +% Maximum size ratio between adjacent cells +% :param slope: +% Maximum relative difference in value between +% adjacent points +% :param curve: +% Maximum relative difference in slope between +% adjacent cells +% :param prune: +% Minimum value for slope or curve for which points +% will be retained in the grid. If the computed +% slope or curve value is below prune for all +% components, it will be deleted, unless either +% neighboring point is already marked for deletion. % if nargin < 3 diff --git a/interfaces/matlab/toolbox/1D/@Stack/setTimeStep.m b/interfaces/matlab/toolbox/1D/@Stack/setTimeStep.m index ccad96246..e5679d8e3 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/setTimeStep.m +++ b/interfaces/matlab/toolbox/1D/@Stack/setTimeStep.m @@ -1,12 +1,15 @@ function setTimeStep(s, stepsize, steps) -% SETTIMESTEP - Specify a sequence of time steps. +% SETTIMESTEP Specify a sequence of time steps. +% setTimeStep(s, stepsize, steps) +% :param stepsize: +% Initial step size (s) +% :param steps: +% Vector of number of steps to take before +% re-attempting solution of steady-state problem. For +% example, steps = [1, 2, 5, 10] would cause one time +% step to be taken first the the steady-state +% solution attempted. If this failed, two time steps +% would be taken, etc. % -% stepsize - initial step size (s) -% steps - array of number of steps to take before -% re-attempting solution of steady-state problem. For -% example, steps = [1, 2, 5, 10] would cause one time -% step to be taken first the the steady-state -% solution attempted. If this failed, two time steps -% would be taken, etc. stack_methods(s.stack_id, 112, stepsize, length(steps), steps) diff --git a/interfaces/matlab/toolbox/1D/@Stack/setValue.m b/interfaces/matlab/toolbox/1D/@Stack/setValue.m index 200e6f2fa..0bf496733 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/setValue.m +++ b/interfaces/matlab/toolbox/1D/@Stack/setValue.m @@ -1,19 +1,26 @@ function setValue(s, n, comp, localPoint, v) -% SETVALUE - Set the value of a single entry in the solution vector. +% SETVALUE Set the value of a single entry in the solution vector. +% setValue(s, n, comp, localPoint, v) +% Example (assuming ``s`` is an instance of :mat:func:`Stack`):: % -% n -- domain number -% comp -- component number -% localPoint -- local index of the grid point in the domain -% v -- value +% setValue(s, 3, 5, 1, 5.6) % -% Example: +% This sets component 5 at the leftmost point (local point 1) in domain 3 +% to the value 5.6. Note that the local index always begins at 1 +% at the left of each domain, independent of the global index of +% the point, which depends on the location of this domain in the +% stack. % -% setValue(s, 3, 5, 1, 5.6) -% -% This sets component 5 at the leftmost point (local point 1) in domain 3 -% to the value 5.6. Note that the local index always begins at 1 -% at the left of each domain, independent of the global index of -% the point, which depends on the location of this domain in the -% stack. +% :param s: +% Instance of class :mat:func:`Stack` +% :param n: +% Domain number +% :param comp: +% Component number +% :param localPoint: +% Local index of the grid point in the domain +% :param v: +% Value % + stack_methods(s.stack_id, 100, n, comp, localPoint, v); diff --git a/interfaces/matlab/toolbox/1D/@Stack/solution.m b/interfaces/matlab/toolbox/1D/@Stack/solution.m index fb7851fc3..5a022d691 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/solution.m +++ b/interfaces/matlab/toolbox/1D/@Stack/solution.m @@ -1,9 +1,19 @@ function x = solution(s, domain, component) -% SOLUTION - get a solution component in one domain. -% -% x = solution(s, 'flow', 'T') returns in vector x the values of -% solution component 'T' in domain 'flow'. +% SOLUTION Get a solution component in one domain. +% x = solution(s, domain, component) +% :param s: +% Instance of class :mat:func:`Stack` +% :param domain: +% String, name of the domain from which the solution is desired +% :param component: +% String, component for which the solution is desired. If omitted, +% solutions for all of the components will be returned in an +% :mat:func:`nPoints` x :mat:func:`nComponents` array. +% :return: +% Either an :mat:func:`nPoints` x 1 vector, or +% :mat:func:`nPoints` x :mat:func:`nComponents` array. % + idom = domainIndex(s, domain); d = s.domains(idom); np = nPoints(d); diff --git a/interfaces/matlab/toolbox/1D/@Stack/solve.m b/interfaces/matlab/toolbox/1D/@Stack/solve.m index e8088dad3..db924b270 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/solve.m +++ b/interfaces/matlab/toolbox/1D/@Stack/solve.m @@ -1,4 +1,14 @@ function solve(s, loglevel, refine_grid) -% SOLVE - +% SOLVE Solve the problem. +% solve(s, loglevel, refine_grid) +% :param s: +% Instance of class :mat:func:`Stack` +% :param loglevel: +% Integer flag controlling the amount of diagnostic +% output. Zero supresses all output, and 5 produces +% very verbose output. +% :param refine_grid: +% Integer, 1 to allow grid refinement, 0 to disallow. % + stack_methods(s.stack_id, 104, loglevel, refine_grid); diff --git a/interfaces/matlab/toolbox/1D/@Stack/subsref.m b/interfaces/matlab/toolbox/1D/@Stack/subsref.m index caa5345bc..ad604125f 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/subsref.m +++ b/interfaces/matlab/toolbox/1D/@Stack/subsref.m @@ -1,5 +1,11 @@ function b = subsref(s, index) -% SUBSREF - +% SUBSREF Redefine subscripted references. +% b = subsref(s,index) +% :param s: +% Instance of class :mat:func:`Stack` +% :param index: +% :return: +% switch index.type case '()' diff --git a/interfaces/matlab/toolbox/1D/@Stack/writeStats.m b/interfaces/matlab/toolbox/1D/@Stack/writeStats.m index e69787a1a..c96359ed5 100644 --- a/interfaces/matlab/toolbox/1D/@Stack/writeStats.m +++ b/interfaces/matlab/toolbox/1D/@Stack/writeStats.m @@ -1,8 +1,12 @@ function writeStats(s) -% WRITESTATS - Print statistics for the current solution. +% WRITESTATS Print statistics for the current solution. +% writeStats(s) +% Prints a summary of the number of function and +% Jacobian evaluations for each grid, and the CPU time spent on +% each one. % -% writeStats(s) prints a summary of the number of function and -% Jacobian evaluations for each grid, and the CPU time spent on -% each one. +% :param s: +% Instance of class :mat:func:`Stack` % + stack_methods(s.stack_id, 108); diff --git a/interfaces/matlab/toolbox/1D/AxiStagnFlow.m b/interfaces/matlab/toolbox/1D/AxiStagnFlow.m index dd14b711b..2e663c8bc 100644 --- a/interfaces/matlab/toolbox/1D/AxiStagnFlow.m +++ b/interfaces/matlab/toolbox/1D/AxiStagnFlow.m @@ -1,6 +1,10 @@ function m = AxiStagnFlow(gas) -% AXISTAGNFLOW - Axisymmetric stagnation flow. -% -% Return a Domain1D instance representing an axisymmetric -% stagnation flow. +% AXISTAGNFLOW Get an axisymmetric stagnation flow domain. +% m = AxiStagnFlow(gas) +% :param gas: +% Instance of class :mat:func:`Solution` +% :return: +% Domain1D instance representing an axisymmetric +% stagnation flow. + m = Domain1D(1, gas); diff --git a/interfaces/matlab/toolbox/1D/AxisymmetricFlow.m b/interfaces/matlab/toolbox/1D/AxisymmetricFlow.m index d681b69e8..bf59b5ab8 100644 --- a/interfaces/matlab/toolbox/1D/AxisymmetricFlow.m +++ b/interfaces/matlab/toolbox/1D/AxisymmetricFlow.m @@ -1,8 +1,14 @@ function m = AxisymmetricFlow(gas, id) -% AXISYMMETRICFLOW - Axisymmetric flow. -% -% Return a Domain1D instance representing an axisymmetric flow. +% AXISYMMETRICFLOW Create an axisymmetric flow domain. +% m = AxisymmetricFlow(gas, id) +% :param gas: +% Instance of class :mat:func:`Solution` +% :param id: +% String, ID of the flow +% :return: +% Domain1D instance representing an axisymmetric flow. % + m = Domain1D(1, gas); if nargin == 1 setID(m, 'flow'); diff --git a/interfaces/matlab/toolbox/1D/FreeFlame.m b/interfaces/matlab/toolbox/1D/FreeFlame.m index 44b298809..00893b6c5 100644 --- a/interfaces/matlab/toolbox/1D/FreeFlame.m +++ b/interfaces/matlab/toolbox/1D/FreeFlame.m @@ -1,9 +1,15 @@ function m = FreeFlame(gas, id) -% FREEFLAME - Freely-propagating flat flame -% -% Return a Domain1D instance representing a freely-propagating -% adiabatic flame +% FREEFLAME Create a freely-propagating flat flame. +% m = FreeFlame(gas, id) +% :param gas: +% Instance of class :mat:func:`Solution` +% :param id: +% String, ID of the flow +% :return: +% Domain1D instance representing a freely propagating, +% adiabatic flame % + m = Domain1D(1, gas, 2); if nargin == 1 setID(m, 'flame'); diff --git a/interfaces/matlab/toolbox/1D/Inlet.m b/interfaces/matlab/toolbox/1D/Inlet.m index f2a0a2cbe..22fb15b3b 100644 --- a/interfaces/matlab/toolbox/1D/Inlet.m +++ b/interfaces/matlab/toolbox/1D/Inlet.m @@ -1,8 +1,15 @@ function m = Inlet(id) -% INLET - Return a Domain1D instance representing an inlet. +% INLET Create an inlet domain. +% m = Inlet(id) +% Note that an inlet can only be a terminal domain - it must be +% either the leftmost or rightmost domain in a stack. % -% Note that an inlet can only be a terminal domain - it must be -% either the leftmost or rightmost domain in a stack. +% :param id: +% String name of the inlet. +% :return: +% Instance of class :mat:func:`Domain1D` representing an inlet. +% + m = Domain1D(2); if nargin == 0 setID(m, 'inlet'); diff --git a/interfaces/matlab/toolbox/1D/Outlet.m b/interfaces/matlab/toolbox/1D/Outlet.m index b8d4bcf50..4e757b003 100644 --- a/interfaces/matlab/toolbox/1D/Outlet.m +++ b/interfaces/matlab/toolbox/1D/Outlet.m @@ -1,6 +1,12 @@ function m = Outlet(id) -% OUTLET - Return a Domain1D instance representing an outlet. +% OUTLET Create an outlet domain. +% m = Outlet(id) +% :param id: +% String ID of the outlet. +% :return: +% Instance of :mat:func:`Domain1D` representing an outlet. % + m = Domain1D(5); if nargin == 0 setID(m, 'outlet'); diff --git a/interfaces/matlab/toolbox/1D/OutletRes.m b/interfaces/matlab/toolbox/1D/OutletRes.m index c82dfbacb..39b515b54 100644 --- a/interfaces/matlab/toolbox/1D/OutletRes.m +++ b/interfaces/matlab/toolbox/1D/OutletRes.m @@ -1,6 +1,11 @@ function m = OutletRes(id) -% OUTLET - Return a Domain1D instance representing an outlet reservoir. +% OUTLETRES Create an outlet reservoir domain. +% m = OutletRes(id) +% :return: +% Instance of :mat:func:`Domain1D` representing an outlet +% reservoir. % + m = Domain1D(-2); if nargin == 0 setID(m, 'outletres'); diff --git a/interfaces/matlab/toolbox/1D/Surface.m b/interfaces/matlab/toolbox/1D/Surface.m index 0d8753ed1..37fd1229a 100644 --- a/interfaces/matlab/toolbox/1D/Surface.m +++ b/interfaces/matlab/toolbox/1D/Surface.m @@ -1,6 +1,16 @@ function m = Surface(id, surface_mech) -% SURFACE - Return a Domain1D instance representing a non-reacting -% or reacting surface. +% SURFACE Create a surface domain. +% m = Surface(id, surface_mech) +% :param id: +% String ID of surface +% :param surface_mech: +% Instance of class :mat:func:`Interface` defining +% the surface reaction mechanism to be used. Optional. +% :return: +% Instance of class :mat:func:`Domain1D` representing a +% non-reacting or reacting surface. +% + if nargin < 2 m = Domain1D(3); if nargin == 0 diff --git a/interfaces/matlab/toolbox/1D/SymmPlane.m b/interfaces/matlab/toolbox/1D/SymmPlane.m index c66bd4b74..99e0bce2b 100644 --- a/interfaces/matlab/toolbox/1D/SymmPlane.m +++ b/interfaces/matlab/toolbox/1D/SymmPlane.m @@ -1,6 +1,13 @@ function m = SymmPlane(id) -% SYMMPLANE - Return a Domain1D instance representing a symmetry plane. +% SYMMPLANE Create a symmetry plane domain. +% m = SymmPlane(id) +% :param id: +% String ID of the symmetry plane. +% :return: +% Instance of class :mat:func:`Domain1D` representing a symmetry +% plane. % + m = Domain1D(4); if nargin == 0 setID(m, 'symmetry_plane'); diff --git a/interfaces/matlab/toolbox/1D/npflame_init.m b/interfaces/matlab/toolbox/1D/npflame_init.m index 787d2f78d..09fbed6fb 100644 --- a/interfaces/matlab/toolbox/1D/npflame_init.m +++ b/interfaces/matlab/toolbox/1D/npflame_init.m @@ -1,20 +1,32 @@ function flame = npflame_init(gas, left, flow, right, fuel, oxidizer, nuox) -% FLAME - create a non-premixed flame object. -% -% gas -- object representing the gas. This object will be used to -% compute all required thermodynamic, kinetic, and transport -% properties. The state of this object should be set -% to an estimate of the gas state emerging from the -% burner before calling StagnationFlame. -% -% left -- object representing the left inlet, which must be -% created using function Inlet. -% -% flow -- object representing the flow, created with -% function AxisymmetricFlow. -% -% right -- object representing the right inlet, which must be -% created using function Inlet. +% NPFLAME_INIT Create a non-premixed flame stack. +% flame = npflame_init(gas, left, flow, right, fuel, oxidizer, nuox) +% :param gas: +% Object representing the gas, instance of class +% :mat:func:`Solution`, and an ideal gas. This object will be used +% to compute all required thermodynamic, kinetic, and transport +% properties. The state of this object should be set +% to an estimate of the gas state emerging from the +% burner before calling StagnationFlame. +% :param left: +% Object representing the left inlet, which must be +% created using function :mat:func:`Inlet`. +% :param flow: +% Object representing the flow, created with +% function :mat:func:`AxisymmetricFlow`. +% :param right: +% Object representing the right inlet, which must be +% created using function :mat:func:`Inlet`. +% :param fuel: +% String representing the fuel species +% :param ox: +% String representing the oxidizer species +% :param nuox: +% Number of oxidizer molecules required to completely combust +% one fuel molecule. +% :return: +% Instance of :mat:func:`Stack` object representing the left +% inlet, flow, and right inlet. % % Check input parameters diff --git a/interfaces/matlab/toolbox/@FlowDevice/FlowDevice.m b/interfaces/matlab/toolbox/@FlowDevice/FlowDevice.m index c8159b800..d34c78afc 100644 --- a/interfaces/matlab/toolbox/@FlowDevice/FlowDevice.m +++ b/interfaces/matlab/toolbox/@FlowDevice/FlowDevice.m @@ -1,5 +1,25 @@ function x = FlowDevice(typ) +% FLOWDEVICE FlowDevice class constructor. +% x = FlowDevice(typ) +% Base class for devices that allow flow between reactors. +% :mat:func:`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 :mat:func:`FlowDevice`, and the +% pressure difference equals the difference in pressure between the +% upstream and downstream reactors. % +% See also: :mat:func:`MassFlowController`, :mat:func:`Valve` +% +% :param typ: +% Type of :mat:func:`FlowDevice` to be created. ``typ=1`` for +% :mat:func:`MassFlowController` and ``typ=3`` for +% :mat:func:`Valve` +% :return: +% Instance of class :mat:func:`FlowDevice` +% + if nargin == 0 typ = 1; end diff --git a/interfaces/matlab/toolbox/@FlowDevice/clear.m b/interfaces/matlab/toolbox/@FlowDevice/clear.m index 547251854..ee7f73ed8 100644 --- a/interfaces/matlab/toolbox/@FlowDevice/clear.m +++ b/interfaces/matlab/toolbox/@FlowDevice/clear.m @@ -1,5 +1,8 @@ function clear(f) -% CLEAR - +% CLEAR Clear the specified flow device from memory. +% clear(f) +% :param f: +% Instance of :mat:func:`FlowDevice` to be cleared. % flowdevicemethods(1, f.index); diff --git a/interfaces/matlab/toolbox/@FlowDevice/install.m b/interfaces/matlab/toolbox/@FlowDevice/install.m index 65a63cd13..ae3244bfd 100644 --- a/interfaces/matlab/toolbox/@FlowDevice/install.m +++ b/interfaces/matlab/toolbox/@FlowDevice/install.m @@ -1,4 +1,15 @@ function install(f, upstream, downstream) +% INSTALL Install a flow device between reactors or reservoirs. +% install(f, upstream, downstream) +% :param f: +% Instance of class :mat:func:`FlowDevice` to install +% :param upstream: +% Upstream :mat:func:`Reactor` or :mat:func:`Reservoir` +% :param downstream: +% Downstream :mat:func:`Reactor` or :mat:func:`Reservoir` +% :return: +% Instance of class :mat:func:`FlowDevice` +% if nargin == 3 if ~isa(upstream, 'Reactor') || ~isa(downstream, 'Reactor') diff --git a/interfaces/matlab/toolbox/@FlowDevice/massFlowRate.m b/interfaces/matlab/toolbox/@FlowDevice/massFlowRate.m index 5094a2e66..8a6d1f6be 100644 --- a/interfaces/matlab/toolbox/@FlowDevice/massFlowRate.m +++ b/interfaces/matlab/toolbox/@FlowDevice/massFlowRate.m @@ -1,4 +1,12 @@ function mdot = massFlowRate(f, time) -% MASSFLOWRATE - mass flow rate in kg/s +% MASSFLOWRATE Get the mass flow rate at a given time. +% mdot = massFlowRate(f, time) +% :param f: +% Instance of class :mat:func:`MassFlowController` +% :param time: +% Time at which the mass flow rate is desired +% :return: +% The mass flow rate through the :mat:func:`FlowDevice` at the given time % + mdot = flowdevicemethods(21, f.index, time); diff --git a/interfaces/matlab/toolbox/@FlowDevice/setFunction.m b/interfaces/matlab/toolbox/@FlowDevice/setFunction.m index 96fdc0ecc..42ecbd90d 100644 --- a/interfaces/matlab/toolbox/@FlowDevice/setFunction.m +++ b/interfaces/matlab/toolbox/@FlowDevice/setFunction.m @@ -1,6 +1,15 @@ function setFunction(f, mf) -% SETMASSFLOWRATE - +% SETFUNCTION Set the mass flow rate with class :mat:func:`Func`. +% setFunction(f, mf) % +% See also: :mat:func:`MassFlowController`, :mat:func:`Func` +% +% :param f: +% Instance of class :mat:func:`MassFlowController` +% :param mf: +% Instance of class :mat:func:`Func` +% + if f.type == 1 k = flowdevicemethods(5, f.index, func_hndl(mf)); if k < 0 diff --git a/interfaces/matlab/toolbox/@FlowDevice/setMassFlowRate.m b/interfaces/matlab/toolbox/@FlowDevice/setMassFlowRate.m index 315b20c50..69e2d287b 100644 --- a/interfaces/matlab/toolbox/@FlowDevice/setMassFlowRate.m +++ b/interfaces/matlab/toolbox/@FlowDevice/setMassFlowRate.m @@ -1,5 +1,13 @@ function setMassFlowRate(f, mdot) -% SETMASSFLOWRATE - +% SETMASSFLOWRATE Set the mass flow rate to a constant value. +% setMassFlowRate(f, mdot) +% +% See also: :mat:func:`MassFlowController` +% +% :param f: +% Instance of class :mat:func:`MassFlowController` +% :param mdot: +% Mass flow rate % if f.type == 1 k = flowdevicemethods(3, f.index, mdot); diff --git a/interfaces/matlab/toolbox/@FlowDevice/setValveCoeff.m b/interfaces/matlab/toolbox/@FlowDevice/setValveCoeff.m index de55990b2..09f021bc4 100644 --- a/interfaces/matlab/toolbox/@FlowDevice/setValveCoeff.m +++ b/interfaces/matlab/toolbox/@FlowDevice/setValveCoeff.m @@ -1,6 +1,21 @@ function setValveCoeff(f, k) -% SETVALVECOEFF - set valve coefficient +% SETVALVECOEFF Set the valve coefficient :math:`K`. +% setValveCoeff(f, k) +% The mass flow rate [kg/s] is computed from the expression % +% .. math:: \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: :mat:func:`Valve` +% +% :param f: +% Instance of class :mat:func:`Valve` +% :param k: +% Value of the valve coefficient. Units: kg/Pa-s +% + if f.type ~= 3 error('Valve coefficient can only be set for valves') end diff --git a/interfaces/matlab/toolbox/@Func/Func.m b/interfaces/matlab/toolbox/@Func/Func.m index abf5bbdbd..7365340a3 100644 --- a/interfaces/matlab/toolbox/@Func/Func.m +++ b/interfaces/matlab/toolbox/@Func/Func.m @@ -1,31 +1,56 @@ function x = Func(typ, n, p) -% -% Func - a class for functors. -% +% FUNC Func class constructor. +% x = Func(typ, n, p) +% 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 '()' +% 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 +% ``f`` is a functor that evaluates the polynomial :math:`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: :mat:func:`polynom`, :mat:func:`gaussian`, :mat:func:`plus`, +% :mat:func:`rdivide`, :mat:func:`times` +% +% :param typ: +% String indicating type of functor to create. Possible values are: +% +% * ``'polynomial'`` +% * ``'fourier'`` +% * ``'gaussian'`` +% * ``'arrhenius'`` +% * ``'sum'`` +% * ``'diff'`` +% * ``'ratio'`` +% * ``'composite'`` +% * ``'periodic'`` +% +% :param n: +% Number of parameters required for the functor +% :param p: +% Vector of parameters +% :return: +% Instance of class :mat:func:`Func` + if ~isa(typ, 'char') error('Function type must be a string') end diff --git a/interfaces/matlab/toolbox/@Func/char.m b/interfaces/matlab/toolbox/@Func/char.m index 2f80b7a82..e7f963402 100644 --- a/interfaces/matlab/toolbox/@Func/char.m +++ b/interfaces/matlab/toolbox/@Func/char.m @@ -1,6 +1,12 @@ function s = char(p) -% CHAR - +% CHAR Get the formatted string to display the function. +% s = char(p) +% :param p: +% Instance of class :mat:func:`Func` +% :return: +% Formatted string displaying the function % + if strcmp(p.typ,'sum') s = ['(' char(p.f1) ') + (' char(p.f2) ')']; elseif strcmp(p.typ,'diff') diff --git a/interfaces/matlab/toolbox/@Func/display.m b/interfaces/matlab/toolbox/@Func/display.m index 5bcd88136..55534fa89 100644 --- a/interfaces/matlab/toolbox/@Func/display.m +++ b/interfaces/matlab/toolbox/@Func/display.m @@ -1,6 +1,10 @@ function display(a) -% DISPLAY - +% DISPLAY Display the equation of the input function on the terminal. +% display(a) +% :param a: +% Instance of class :mat:func:`Func` % + disp(' '); disp([inputname(1),' = ']) disp(' '); diff --git a/interfaces/matlab/toolbox/@Func/func_hndl.m b/interfaces/matlab/toolbox/@Func/func_hndl.m index 4a6af7096..7ab6fe028 100644 --- a/interfaces/matlab/toolbox/@Func/func_hndl.m +++ b/interfaces/matlab/toolbox/@Func/func_hndl.m @@ -1,4 +1,10 @@ function i = func_hndl(f) -% FUNC_HNDL - +% FUNC_HNDL Get the integer used to access the kernel object. +% i = func_hndl(f) +% :param f: +% Instance of class :mat:func:`Func` +% :return: +% The handle of the input function % + i = f.index; diff --git a/interfaces/matlab/toolbox/@Func/plus.m b/interfaces/matlab/toolbox/@Func/plus.m index b98b946e9..434cb1db0 100644 --- a/interfaces/matlab/toolbox/@Func/plus.m +++ b/interfaces/matlab/toolbox/@Func/plus.m @@ -1,4 +1,12 @@ function r = plus(a, b) +% PLUS Get a functor representing the sum of two input functors. +% r = plus(a, b) +% :param a: +% Instance of class :mat:func:`Func` +% :param b: +% Instance of class :mat:func:`Func` +% :return: +% Instance of class :mat:func:`Func` % % PLUS - Return a functor representing the sum of two functors a % and b. diff --git a/interfaces/matlab/toolbox/@Func/rdivide.m b/interfaces/matlab/toolbox/@Func/rdivide.m index 49b12647d..d7c19e9a6 100644 --- a/interfaces/matlab/toolbox/@Func/rdivide.m +++ b/interfaces/matlab/toolbox/@Func/rdivide.m @@ -1,5 +1,12 @@ function r = rdivide(a, b) -% RDIVIDE - +% RDIVIDE Get a functor that is the ratio of the input functors. +% r = rdivide(a,b) +% :param a: +% Instance of class :mat:func:`Func` +% :param b: +% Instance of class :mat:func:`Func` +% :return: +% Instance of class :mat:func:`Func` % r = Func('ratio', a, b); diff --git a/interfaces/matlab/toolbox/@Func/subsref.m b/interfaces/matlab/toolbox/@Func/subsref.m index 453b4beaf..6be0bf716 100644 --- a/interfaces/matlab/toolbox/@Func/subsref.m +++ b/interfaces/matlab/toolbox/@Func/subsref.m @@ -1,5 +1,14 @@ function b = subsref(a, s) -% SUBSREF +% SUBSREF Redefine subscripted references for functors. +% b = subsref(a, s) +% :param a: +% Instance of class :mat:func:`Func` +% :param s: +% Value at which the function should be evaluated. +% :return: +% Returns the value of the function evaluated at ``s`` +% + switch s.type case '()' ind = s.subs{:}; diff --git a/interfaces/matlab/toolbox/@Func/times.m b/interfaces/matlab/toolbox/@Func/times.m index 0f6056bd1..97e9ddb27 100644 --- a/interfaces/matlab/toolbox/@Func/times.m +++ b/interfaces/matlab/toolbox/@Func/times.m @@ -1,5 +1,12 @@ function r = times(a, b) -% TIMES - +% TIMES Create a functor that multiplies two other functors. +% r = times(a, b) +% :param a: +% Instance of class :mat:func:`Func` +% :param b: +% Instance of class :mat:func:`Func` +% :return: +% Instance of class :mat:func:`Func` % r = Func('prod', a, b); diff --git a/interfaces/matlab/toolbox/@Interface/Interface.m b/interfaces/matlab/toolbox/@Interface/Interface.m index db33c6570..d9b2f46bd 100644 --- a/interfaces/matlab/toolbox/@Interface/Interface.m +++ b/interfaces/matlab/toolbox/@Interface/Interface.m @@ -1,6 +1,26 @@ function s = Interface(src, id, p1, p2, p3, p4) -% Interface - class Interface constructor. +% INTERFACE Interface class constructor. +% s = Interface(src, id, p1, p2, p3, p4) +% See :ref:`sec-interfaces`. % +% See also: :mat:func:`importEdge`, :mat:func:`importInterface` +% +% :param src: +% CTI or CTML file containing the interface or edge phase. +% :param id: +% Name of the interface or edge phase in the CTI or CTML file. +% :param p1: +% Adjoining phase to the interface. +% :param p2: +% Adjoining phase to the interface. +% :param p3: +% Adjoining phase to the interface. +% :param p4: +% Adjoining phase to the interface. +% :return: +% Instance of class :mat:func:`Interface` +% + doc = XML_Node('doc', src); node = findByID(doc, id); t = ThermoPhase(node); diff --git a/interfaces/matlab/toolbox/@Interface/concentrations.m b/interfaces/matlab/toolbox/@Interface/concentrations.m index e16fd10c4..fb3b7c7f2 100644 --- a/interfaces/matlab/toolbox/@Interface/concentrations.m +++ b/interfaces/matlab/toolbox/@Interface/concentrations.m @@ -1,6 +1,14 @@ function c = concentrations(s) -% CONCENTRATIONS - Surface concentrations +% CONCENTRATIONS Get the concentrations of the species on an interface. +% c = concentrations(s) +% :param s: +% Instance of class :mat:func:`Interface` with surface species +% :return: +% If no output value is assigned, a bar graph will be plotted. +% Otherwise, a vector of length ``n_surf_species`` will be +% returned. % + c = surfmethods(thermo_hndl(s), 103); if nargout == 0 figure diff --git a/interfaces/matlab/toolbox/@Interface/coverages.m b/interfaces/matlab/toolbox/@Interface/coverages.m index 140382d34..8bf4c1688 100644 --- a/interfaces/matlab/toolbox/@Interface/coverages.m +++ b/interfaces/matlab/toolbox/@Interface/coverages.m @@ -1,6 +1,14 @@ function c = coverages(s) -% COVERAGES - Surface coverages +% COVERAGES Get the surface coverages of the species on an interface. +% c = coverages(s) +% :param s: +% Instance of class :mat:func:`Interface` with surface species +% :return: +% If no output value is assigned, a bar graph will be plotted. +% Otherwise, a vector of length ``n_surf_species`` will be +% returned. % + c = surfmethods(thermo_hndl(s), 101); if nargout == 0 figure diff --git a/interfaces/matlab/toolbox/@Interface/setCoverages.m b/interfaces/matlab/toolbox/@Interface/setCoverages.m index 55127ab51..d2985684d 100644 --- a/interfaces/matlab/toolbox/@Interface/setCoverages.m +++ b/interfaces/matlab/toolbox/@Interface/setCoverages.m @@ -1,6 +1,14 @@ function setCoverages(s, cov) -% SETCOVERAGES - set surface coverages +% SETCOVERAGES Set surface coverages of the species on an interface. +% setCoverages(s, cov) +% :param s: +% Instance of class :mat:func:`Interface` +% :param cov: +% Coverage of the species. ``cov`` can be either a vector of +% length ``n_surf_species``, or a string in the format +% ``'Species:Coverage, Species:Coverage'`` % + if isa(cov, 'double') sz = length(cov); if sz == nSpecies(s) diff --git a/interfaces/matlab/toolbox/@Kinetics/Kinetics.m b/interfaces/matlab/toolbox/@Kinetics/Kinetics.m index 839844fc4..2112866d3 100644 --- a/interfaces/matlab/toolbox/@Kinetics/Kinetics.m +++ b/interfaces/matlab/toolbox/@Kinetics/Kinetics.m @@ -1,10 +1,34 @@ function k = Kinetics(r, ph, neighbor1, neighbor2, neighbor3, neighbor4) +% KINETICS Kinetics class constructor. +% k = Kinetics(r, ph, neighbor1, neighbor2, neighbor3, neighbor4) +% Class Kinetics represents kinetics managers, which are classes +% that manage reaction mechanisms. The reaction mechanism +% attributes are specified in a CTML file. +% Instances of class :mat:func:`Kinetics` are responsible for evaluating reaction rates +% of progress, species production rates, and other quantities pertaining to +% a reaction mechanism. % -% KINETICS - Kinetics class constructor. -% -% Class Kinetics represents kinetics managers, which are classes -% that manage reaction mechanisms. The reaction mechanism -% attributes are specified in a CTML file. +% :param r: +% If ``r`` is an instance of class :mat:func:`Kinetics`, a copy of the instance +% is returned. In this case, ``r`` should be the only argument. Otherwise, ``r`` +% must be an instance of class :mat:func:`XML_Node`. +% :param ph: +% If ``r`` is an instance of :mat:func:`XML_Node`, ``ph`` is an instance of class +% :mat:func:`ThermoPhase`. Otherwise, optional. +% :param neighbor1: +% Instance of class :mat:func:`ThermoPhase` or :mat:func:`Solution` representing a +% neighboring phase. +% :param neighbor2: +% Instance of class :mat:func:`ThermoPhase` or :mat:func:`Solution` representing a +% neighboring phase. +% :param neighbor3: +% Instance of class :mat:func:`ThermoPhase` or :mat:func:`Solution` representing a +% neighboring phase. +% :param neighbor4: +% Instance of class :mat:func:`ThermoPhase` or :mat:func:`Solution` representing a +% neighboring phase. +% :return: +% Instance of class :mat:func:`Kinetics` % % indices for bulk phases in a heterogeneous mechanism. diff --git a/interfaces/matlab/toolbox/@Kinetics/advanceCoverages.m b/interfaces/matlab/toolbox/@Kinetics/advanceCoverages.m index 8e334cf45..ce6e8d330 100644 --- a/interfaces/matlab/toolbox/@Kinetics/advanceCoverages.m +++ b/interfaces/matlab/toolbox/@Kinetics/advanceCoverages.m @@ -1,4 +1,13 @@ function advanceCoverages(k, dt) -% ADVANCECOVERAGES - advance the surface coverages forward in time holding the bulk phase concentrations fixed. +% ADVANCECOVERAGES Advance the surface coverages forward in time. +% advanceCoverages(k, dt) +% The bulk phase concentrations are held fixed during this operation. % +% :param k: +% Instance of class :mat:func:`Interface` with an associated +% :mat:func:`Kinetics` object. +% :param dt: +% Time interval by which the coverages should be advanced +% + kinetics_set(k.id, 5, 0, dt); diff --git a/interfaces/matlab/toolbox/@Kinetics/clear.m b/interfaces/matlab/toolbox/@Kinetics/clear.m index d3e60fe21..eeffee750 100644 --- a/interfaces/matlab/toolbox/@Kinetics/clear.m +++ b/interfaces/matlab/toolbox/@Kinetics/clear.m @@ -1,5 +1,9 @@ function clear(k) -% CLEAR - delete the Kinetics instance. +% CLEAR Delete the Kinetics instance. +% clear(k) +% :param k: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) % kinetics_set(k.id, 3, 0, 0); diff --git a/interfaces/matlab/toolbox/@Kinetics/creationRates.m b/interfaces/matlab/toolbox/@Kinetics/creationRates.m index 3b4fa4901..ebf1863c0 100644 --- a/interfaces/matlab/toolbox/@Kinetics/creationRates.m +++ b/interfaces/matlab/toolbox/@Kinetics/creationRates.m @@ -1,14 +1,19 @@ function cdot = creationRates(a) -% CREATIONRATES Chemical creation rates (kmol/m^3/s). +% CREATIONRATES Get the chemical creation rates. +% cdot = creationRates(a) % -% cdot = creationRates(K) +% See also: :mat:func:`destructionRates`, :mat:func:`netProdRates` % -% Returns a column vector of the creation rates of all -% species. If the output is not assigned to a variable, a -% bar graph is produced. -% -% See also: destructionRates, netProdRates. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which creation rates are desired. +% :return: +% Returns a column vector of the creation rates of all +% species. If the output is not assigned to a variable, a +% bar graph is produced. Units: kmol/m**3-s % + cdot = kinetics_get(a.id, 21, 0); if nargout == 0 figure diff --git a/interfaces/matlab/toolbox/@Kinetics/destructionRates.m b/interfaces/matlab/toolbox/@Kinetics/destructionRates.m index 4e1c01a38..048252c98 100644 --- a/interfaces/matlab/toolbox/@Kinetics/destructionRates.m +++ b/interfaces/matlab/toolbox/@Kinetics/destructionRates.m @@ -1,14 +1,19 @@ function ddot = destructionRates(a) -% destructionRates Chemical destruction rates (kmol/m^3/s). +% DESTRUCTIONRATES Get the chemical destruction rates. +% ddot = destructionRates(a) % -% cdot = destructionRates(a) +% See also: :mat:func:`creationRates`, :mat:func:`netProdRates` % -% Returns a column vector of the destruction rates of all -% species. If the output is not assigned to a variable, a -% bar graph is produced. -% -% See also: creationRates, netProdRates. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which destruction rates are desired. +% :return: +% Returns a column vector of the destruction rates of all +% species. If the output is not assigned to a variable, a +% bar graph is produced. Units: kmol/m**3-s % + ddot = kinetics_get(a.id, 22, 0); if nargout == 0 figure diff --git a/interfaces/matlab/toolbox/@Kinetics/destruction_rates.m b/interfaces/matlab/toolbox/@Kinetics/destruction_rates.m index 7528d47a8..ed9683b57 100644 --- a/interfaces/matlab/toolbox/@Kinetics/destruction_rates.m +++ b/interfaces/matlab/toolbox/@Kinetics/destruction_rates.m @@ -1,13 +1,11 @@ function ddot = destruction_rates(a) -% destruction_rates Chemical destruction rates for all species. -% -% q = destruction_rates(a) -% -% Returns a column vector of the destruction rates of all species. -% -% See also: creation_rates, net_production_rates. +% DESTRUCTION_RATES Get the chemical destruction rates. +% ddot = destruction_rates(a) +% This function is deprecated in favor of the function +% :mat:func:`destructionRates` % +warning('This function is deprecated. Use destructionRates instead.') ddot = destructionRates(a); if nargout == 0 figure diff --git a/interfaces/matlab/toolbox/@Kinetics/equil_Kc.m b/interfaces/matlab/toolbox/@Kinetics/equil_Kc.m index e47c8faa5..95e32957f 100644 --- a/interfaces/matlab/toolbox/@Kinetics/equil_Kc.m +++ b/interfaces/matlab/toolbox/@Kinetics/equil_Kc.m @@ -1,13 +1,19 @@ function kc = equil_Kc(a) -% equil_Kc(a) equilibrium constants for all reactions +% EQUIL_KC Get the equilibrium constants for all reactions +% kc = equil_Kc(a) % -% q = equil_Kc(a) -% -% Returns a column vector of the equilibrium constants -% for all reactions. The vector has an entry for every -% reaction, whether reversible or not, but non-zero values -% occur only for the reversible reactions. +% See also: :mat:func:`fwdRateConstants`, :mat:func:`revRateConstants` % +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which equilibrium constants are desired. +% :return: +% Returns a column vector of the equilibrium constants +% for all reactions. The vector has an entry for every +% reaction, whether reversible or not, but non-zero values +% occur only for the reversible reactions. If the output is +% not assigned to a variable, a bar graph is produced instead. % kc = kinetics_get(a.id, 14, 0); diff --git a/interfaces/matlab/toolbox/@Kinetics/fwdRateConstants.m b/interfaces/matlab/toolbox/@Kinetics/fwdRateConstants.m index ed692fb61..f548d0162 100644 --- a/interfaces/matlab/toolbox/@Kinetics/fwdRateConstants.m +++ b/interfaces/matlab/toolbox/@Kinetics/fwdRateConstants.m @@ -1,9 +1,16 @@ function kf = fwdRateConstants(a) -%FWDRATECONSTANTS Forward reaction rate constants for all the reactions. +% FWDRATECONSTANTS Get the forward reaction rate constants. +% kf = fwdRateConstants(a) % -% kf = fwdRateConstants(a) +% see also: :mat:func:`revRateConstants`, :mat:func:`equil_Kc` % -% Returns a column vector of the forward rate constants of -% all of the reactions. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which forward rate constants are desired. +% :return: +% Returns a column vector of the forward rate constants of +% all of the reactions. % + kf = kinetics_get(a.id, 15, 0); diff --git a/interfaces/matlab/toolbox/@Kinetics/hndl.m b/interfaces/matlab/toolbox/@Kinetics/hndl.m index 4d475990c..d64bfb0be 100644 --- a/interfaces/matlab/toolbox/@Kinetics/hndl.m +++ b/interfaces/matlab/toolbox/@Kinetics/hndl.m @@ -1,4 +1,9 @@ function i = hndl(k) +% HNDL Get the integer used to access kernel objects. +% i = hndl(k) +% Integer used to access kernel objects. Deprecated in favor of +% :mat:func:`kinetics_hndl`. +% warning('This function is deprecated in favor of kinetics_hndl.m') i = k.id; diff --git a/interfaces/matlab/toolbox/@Kinetics/isReversible.m b/interfaces/matlab/toolbox/@Kinetics/isReversible.m index 11d5556ad..e0980f3d1 100644 --- a/interfaces/matlab/toolbox/@Kinetics/isReversible.m +++ b/interfaces/matlab/toolbox/@Kinetics/isReversible.m @@ -1,14 +1,25 @@ function yn = isReversible(a, i) -% ISREVERSIBLE - Reversible reaction flag. +% ISREVERSIBLE Get an array of flags indicating reversibility of a reaction. +% yn = isReversible(a, i) +% A reversible reaction is one that runs in both the forward +% direction (reactants -> products) and in the reverse direction +% (products -> reactants). The reverse rate for reversible +% reactions can computed from thermochemistry, so that the +% reaction satisfies detailed balance, and the net rate of +% progress is zero in states of chemical equilibrium. The reverse +% rate can also be specified directly by a rate expression. An +% irreversible reaction is one whose reverse reaction rate is +% zero. % -% A reversible reaction is one that runs in both the forward -% direction (reactants -> products) and in the reverse direction -% (products -> reactants). The reverse rate for reversible -% reactions is computed from thermochemistry, so that the -% reaction satisfies detailed balance, and the net rate of -% progress is zero in states of chemical equilibrium. -% -% ISREVERSIBLE(K, IRXN) returns 1 if reaction number IRXN is -% reversible, and 0 if it is irreversible. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the reversible flags are desired. +% :param i: +% Integer reaction number +% :return: +% 1 if reaction number ``i`` is +% reversible, and 0 if it is irreversible. % + yn = kinetics_get(a.id, 4, i); diff --git a/interfaces/matlab/toolbox/@Kinetics/kinetics_hndl.m b/interfaces/matlab/toolbox/@Kinetics/kinetics_hndl.m index 1271e64fe..7b2baaa41 100644 --- a/interfaces/matlab/toolbox/@Kinetics/kinetics_hndl.m +++ b/interfaces/matlab/toolbox/@Kinetics/kinetics_hndl.m @@ -1,4 +1,12 @@ function i = kinetics_hndl(k) -% KINETICS_HNDL - integer used to access kernel object +% KINETICS_HNDL Get the integer used to access kernel object. +% i = kinetics_hndl(k) +% :param k: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the handle is desired. +% :return: +% Returns the integer ID of the kinetics kernel object. % + i = k.id; diff --git a/interfaces/matlab/toolbox/@Kinetics/multiplier.m b/interfaces/matlab/toolbox/@Kinetics/multiplier.m index 7d82f2765..6c3627a69 100644 --- a/interfaces/matlab/toolbox/@Kinetics/multiplier.m +++ b/interfaces/matlab/toolbox/@Kinetics/multiplier.m @@ -1,13 +1,21 @@ -function n = multiplier(a, irxn) -% MULTIPLIER Multiplier for reaction rate of progress. +function n = multiplier(a,irxn) +% MULTIPLIER Get the multiplier for reaction rate of progress. +% n = multiplier(a,irxn) +% The multiplier multiplies the reaction rate of progress. It may +% be used to implement sensitivity analysis, or to selectively +% disable reactions. For reversible reactions, it multiplies both +% the forward and reverse rates. By default, the multiplier value +% is 1.0, but it may be set to any other value by calling method +% :mat:func:`setMultiplier`. % -% The multiplier multiplies the reaction rate of progress. It may -% be used to implement sensitivity analysis, or to selectively -% disable reactions. For reversible reactions, it multiplies both -% the forward and reverse rates. By default, the multiplier value -% is 1.0, but it may be set to any other value by calling method -% setMultiplier. -% -% MULTIPLIER(K, IRXN) Multiplier for reaction number IRXN +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the multipliers are desired. +% :param irxn: +% Integer reaction number for which the multiplier is desired. +% :return: +% Multiplier of the rate of progress of reaction number ``irxn`` % + n = kinetics_get(a.id, 2, irxn); diff --git a/interfaces/matlab/toolbox/@Kinetics/nReactions.m b/interfaces/matlab/toolbox/@Kinetics/nReactions.m index 8d26124ed..c2513a1fc 100644 --- a/interfaces/matlab/toolbox/@Kinetics/nReactions.m +++ b/interfaces/matlab/toolbox/@Kinetics/nReactions.m @@ -1,4 +1,12 @@ function n = nReactions(a) -% NREACTIONS - Number of reactions. +% NREACTIONS Get the number of reactions. +% n = nReactions(a) +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the number of reactions is desired. +% :return: +% Integer number of reactions % + n = kinetics_get(a.id, 1, 0); diff --git a/interfaces/matlab/toolbox/@Kinetics/nTotalSpecies.m b/interfaces/matlab/toolbox/@Kinetics/nTotalSpecies.m index 262efaaf7..85d309637 100644 --- a/interfaces/matlab/toolbox/@Kinetics/nTotalSpecies.m +++ b/interfaces/matlab/toolbox/@Kinetics/nTotalSpecies.m @@ -1,5 +1,15 @@ function nsp = nTotalSpecies(a) -% NTOTALSPECIES - The total number of species, summed over all +% NTOTALSPECIES Get the total number of species. +% nsp = nTotalSpecies(a) +% The total number of species, summed over all % participating phases. % +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the number of species is desired. +% :return: +% Integer total number of species +% + nsp = kinetics_get(a.id, 3, 0); diff --git a/interfaces/matlab/toolbox/@Kinetics/netProdRates.m b/interfaces/matlab/toolbox/@Kinetics/netProdRates.m index 524958677..14629a24f 100644 --- a/interfaces/matlab/toolbox/@Kinetics/netProdRates.m +++ b/interfaces/matlab/toolbox/@Kinetics/netProdRates.m @@ -1,14 +1,19 @@ function wdot = netProdRates(a) -% NETPRODRATES Net chemical production rates for all species. +% NETPRODRATES Get the net chemical production rates for all species. +% wdot = netProdRates(a) % -% wdot = netProdRates(a) +% See also: :mat:func:`creationRates`, :mat:func:`destructionRates` % -% Returns a column vector of the net production (creation - -% destruction) rates of all species. If the output is not -% assigned to a variable, a bar plot is produced. -% -% See also: creationRates, destructionRates +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which net production rates are desired. +% :return: +% Returns a column vector of the net production (creation - +% destruction) rates of all species. If the output is not +% assigned to a variable, a bar plot is produced. % + wdot = kinetics_get(a.id, 23, 0); if nargout == 0 figure diff --git a/interfaces/matlab/toolbox/@Kinetics/reactionEqn.m b/interfaces/matlab/toolbox/@Kinetics/reactionEqn.m index da74467a1..220727016 100644 --- a/interfaces/matlab/toolbox/@Kinetics/reactionEqn.m +++ b/interfaces/matlab/toolbox/@Kinetics/reactionEqn.m @@ -1,6 +1,21 @@ function e = reactionEqn(a, irxn) -% reactionEqn Reaction equation of reaction irxn. +% REACTIONEQN Get the reaction equation of a reaction. +% e = reactionEqn(a, irxn) +% If only the first argument +% is given, the reaction equations of all of the reactions are +% returned in a cell array. Otherwise, ``irxn`` must be an integer +% or vector of integers. % +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the reaction equations are desired. +% :param irxn: +% Optional. Integer or vector of integer reaction numbers. +% :return: +% String or cell array of strings of the reaction equations. +% + if nargin == 1 m = nReactions(a); n = 1; diff --git a/interfaces/matlab/toolbox/@Kinetics/revRateConstants.m b/interfaces/matlab/toolbox/@Kinetics/revRateConstants.m index 941436bf1..5a1c5f5df 100644 --- a/interfaces/matlab/toolbox/@Kinetics/revRateConstants.m +++ b/interfaces/matlab/toolbox/@Kinetics/revRateConstants.m @@ -1,9 +1,16 @@ function kr = revRateConstants(a) -%REVRATECONSTANTS Reverse reaction rate constants for all the reactions. +% REVRATECONSTANTS Get the reverse reaction rate constants. +% kr = revRateConstants(a) % -% kr = revRateConstants(a) +% See also: :mat:func:`fwdRateConstants`, :mat:func:`equil_KC` % -% Returns a column vector of the reverse rate constants of -% all of the reactions. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which reverse rate constants are desired. +% :return: +% Returns a column vector of the reverse rate constants of +% all of the reactions. % + kr = kinetics_get(a.id, 16, 0); diff --git a/interfaces/matlab/toolbox/@Kinetics/rop.m b/interfaces/matlab/toolbox/@Kinetics/rop.m index 8d5b8180d..15ea3e49c 100644 --- a/interfaces/matlab/toolbox/@Kinetics/rop.m +++ b/interfaces/matlab/toolbox/@Kinetics/rop.m @@ -1,10 +1,19 @@ function rop = rop(a) -% ROP - Forward and reverse rates of progress. +% ROP Get the forward and reverse rates of progress. +% rop = rop(a) % -% ROP(K) returns an M x 2 array of reaction rates of -% progress. The first column contains the forward rates of progress, -% and the second column the reverse rates. If this function -% is called with no output argument, a bar graph is produced. +% See also: :mat:func:`rop_f`, :mat:func:`rop_r`, :mat:func:`rop_net` +% +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which forward and reverse rates of progress are desired. +% :return: +% Returns an I x 2 array of reaction rates of +% progress, where I is the number of reactions. The first +% column contains the forward rates of progress, and the +% second column the reverse rates. If this function +% is called with no output argument, a bar graph is produced. % f = rop_f(a); diff --git a/interfaces/matlab/toolbox/@Kinetics/rop_f.m b/interfaces/matlab/toolbox/@Kinetics/rop_f.m index fb9172ded..fbbf45975 100644 --- a/interfaces/matlab/toolbox/@Kinetics/rop_f.m +++ b/interfaces/matlab/toolbox/@Kinetics/rop_f.m @@ -1,13 +1,19 @@ function q = rop_f(a) % ROP_F Forward rates of progress for all reactions. +% q = rop_f(a) % -% Q = ROP_F(K) +% See also: :mat:func:`rop_r`, :mat:func:`rop_net`, :mat:func:`rop` % -% Returns a column vector of the forward rates of progress -% for all reactions. -% -% See also: rop_r, rop_net. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which forward rates of progress are desired. +% :return: +% Returns a column vector of the forward rates of progress +% for all reactions. If this function +% is called with no output argument, a bar graph is produced. % + q = kinetics_get(a.id, 11, 0); if nargout == 0 figure diff --git a/interfaces/matlab/toolbox/@Kinetics/rop_net.m b/interfaces/matlab/toolbox/@Kinetics/rop_net.m index d18409f58..7786f1e22 100644 --- a/interfaces/matlab/toolbox/@Kinetics/rop_net.m +++ b/interfaces/matlab/toolbox/@Kinetics/rop_net.m @@ -1,12 +1,17 @@ function q = rop_net(a) -% ROP_F Forward rates of progress for all reactions. +% ROP_NET Net rates of progress for all reactions. +% q = rop_net(a) % -% Q = ROP_F(K) +% See also: :mat:func:`rop_f`, :mat:func:`rop_r`, :mat:func:`rop` % -% Returns a column vector of the forward rates of progress -% for all reactions. -% -% See also: rop_r, rop_net. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the net rates of progress are desired. +% :return: +% Returns a column vector of the net rates of progress +% for all reactions. If this function +% is called with no output argument, a bar graph is produced. % q = kinetics_get(a.id, 13, 0); diff --git a/interfaces/matlab/toolbox/@Kinetics/rop_r.m b/interfaces/matlab/toolbox/@Kinetics/rop_r.m index 28dfd1f13..dc28ebec8 100644 --- a/interfaces/matlab/toolbox/@Kinetics/rop_r.m +++ b/interfaces/matlab/toolbox/@Kinetics/rop_r.m @@ -1,14 +1,19 @@ function q = rop_r(a) -% ROP_R Reverse rates of progress for all reactions. +% ROP_R Get the reverse rates of progress for all reactions. +% q = rop_r(a) % -% Q = ROP_R(K) +% See also: :mat:func:`rop_f`, :mat:func:`rop_net`, :mat:func:`rop` % -% Returns a column vector of the reverse rates of progress -% for all reactions. The value is zero for irreversible -% reactions. -% -% See also: rop_r, rop_net. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which reverse rates of progress are desired. +% :return: +% Returns a column vector of the reverse rates of progress +% for all reactions. If this function +% is called with no output argument, a bar graph is produced. % + q = kinetics_get(a.id, 12, 0); if nargout == 0 figure diff --git a/interfaces/matlab/toolbox/@Kinetics/setMultiplier.m b/interfaces/matlab/toolbox/@Kinetics/setMultiplier.m index 97bac15de..b0a66c289 100644 --- a/interfaces/matlab/toolbox/@Kinetics/setMultiplier.m +++ b/interfaces/matlab/toolbox/@Kinetics/setMultiplier.m @@ -1,11 +1,27 @@ function setMultiplier(a, irxn, v) -% SETMULTIPLIER Set the rate of progress multiplier. +% SETMULTIPLIER Set the multiplier for the reaction rate of progress. +% setMultiplier(a,irxn,v) +% The multiplier multiplies the reaction rate of progress. It may +% be used to implement sensitivity analysis, or to selectively +% disable reactions. For reversible reactions, it multiplies both +% the forward and reverse rates. By default, the multiplier value +% is 1.0, but the current value may be checked by calling method +% :mat:func:`multiplier`. % -% SETMULTIPLIER(K, IRXN, V) sets the multipler for reaction IRXN -% to value V. +% If only two arguments are given, it is assumed that the second is +% the desired multiplication factor for all of the reactions. % -% see also: MULTIPLIER +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the multipliers should be set. +% :param irxn: +% Integer or vector of integers. Reaction number(s) for which +% the multiplier should be set. Optional. +% :param v: +% Value by which the reaction rate of progress should be multiplied % + if nargin == 2 v = irxn; m = nReactions(a); diff --git a/interfaces/matlab/toolbox/@Kinetics/stoich_net.m b/interfaces/matlab/toolbox/@Kinetics/stoich_net.m index ae24f2b42..cb74419da 100644 --- a/interfaces/matlab/toolbox/@Kinetics/stoich_net.m +++ b/interfaces/matlab/toolbox/@Kinetics/stoich_net.m @@ -1,25 +1,32 @@ function nu = stoich_net(a, species, rxns) -% stoich_net Net stoichiometric coefficients. +% STOICH_NET Get the net stoichiometric coefficients. +% nu = stoich_net(a,species,rxns) % -% nu = stoich_net(a) +% See also: :mat:func:`stoich_r`, :mat:func:`stoich_p` % -% Returns a sparse matrix of all net (product - reactant) -% stoichiometric coefficients. The matrix element nu(k,i) is the -% net stoichiometric coefficient of species k in reaction i. -% -% nu = stoich_net(a, species, rxns) -% -% Returns a sparse matrix the same size as above, but -% containing only entries for the specified species and -% reactions. For example, stoich_net(a,3,[1 3 5 7]) returns a -% sparse matrix containing only the coefficients for species 3 -% in reactions 1, 3, 5, and 7. -% -% Note that the net stoichiometric coefficients may be negative, -% unlike the reactant or product stoichiometric coefficients. -% -% See also: stoich_r, stoich_p. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the net stoichiometric coefficients are desired. +% :param species: +% Species indices for which net stoichiometric coefficients +% should be retrieved. Optional argument; if specified, ``rxns`` +% must be specified as well. +% :param rxns: +% Reaction indices for which net stoichiometric coefficients +% should be retrieved. Optional argument; if specified, ``species`` +% must be specified as well. +% :return: +% Returns a sparse matrix of all net stoichiometric +% coefficients. The matrix element ``nu(k,i)`` is the +% stoichiometric coefficient of species k as a net in +% reaction i. If ``species`` and ``rxns`` are specified, the matrix +% will contain only entries for the specified species and +% reactions. For example, ``stoich_p(a,3,[1 3 5 7])`` returns a +% sparse matrix containing only the coefficients for species 3 +% in reactions 1, 3, 5, and 7. % + if nargin == 1 nu = stoich_p(a) - stoich_r(a); elseif nargin == 3 diff --git a/interfaces/matlab/toolbox/@Kinetics/stoich_p.m b/interfaces/matlab/toolbox/@Kinetics/stoich_p.m index ed3504b66..b96e115ca 100644 --- a/interfaces/matlab/toolbox/@Kinetics/stoich_p.m +++ b/interfaces/matlab/toolbox/@Kinetics/stoich_p.m @@ -1,23 +1,32 @@ function nu_p = stoich_p(a, species, rxns) -% stoich_p Product stoichiometric coefficients. +% STOICH_P Get the product stoichiometric coefficients. +% nu_p = stoich_p(a,species,rxns) % -% nu = stoich_p(a) +% See also: :mat:func:`stoich_r`, :mat:func:`stoich_net` % -% Returns a sparse matrix of all product stoichiometric -% coefficients. The matrix element nu(k,i) is the -% stoichiometric coefficient of species k as a product in -% reaction i. -% -% nu = stoich_p(a, species, rxns) -% -% Returns a sparse matrix the same size as above, but -% containing only entries for the specified species and -% reactions. For example, stoich_p(a,3,[1 3 5 7]) returns a -% sparse matrix containing only the coefficients for species 3 -% in reactions 1, 3, 5, and 7. -% -% See also: stoich_r, stoich_net. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the product stoichiometric coefficients are desired. +% :param species: +% Species indices for which product stoichiometric coefficients +% should be retrieved. Optional argument; if specified, ``rxns`` +% must be specified as well. +% :param rxns: +% Reaction indices for which product stoichiometric coefficients +% should be retrieved. Optional argument; if specified, ``species`` +% must be specified as well. +% :return: +% Returns a sparse matrix of all product stoichiometric +% coefficients. The matrix element ``nu(k,i)`` is the +% stoichiometric coefficient of species k as a product in +% reaction i. If ``species`` and ``rxns`` are specified, the matrix +% will contain only entries for the specified species and +% reactions. For example, ``stoich_p(a,3,[1 3 5 7])`` returns a +% sparse matrix containing only the coefficients for species 3 +% in reactions 1, 3, 5, and 7. % + nsp = nTotalSpecies(a); nr = nReactions(a); b = sparse(nsp, nr); diff --git a/interfaces/matlab/toolbox/@Kinetics/stoich_r.m b/interfaces/matlab/toolbox/@Kinetics/stoich_r.m index a4df22fd8..ec7fe98bb 100644 --- a/interfaces/matlab/toolbox/@Kinetics/stoich_r.m +++ b/interfaces/matlab/toolbox/@Kinetics/stoich_r.m @@ -1,23 +1,32 @@ function nu_r = stoich_r(a, species, rxns) -% stoich_r Reactant stoichiometric coefficients. +% STOICH_R Get the reactant stoichiometric coefficients. +% nu_r = stoich_r(a,species,rxns) % -% nu = stoich_r(a) +% See also: :mat:func:`stoich_p`, :mat:func:`stoich_net` % -% Returns a sparse matrix of all reactant stoichiometric -% coefficients. The matrix element nu(k,i) is the -% stoichiometric coefficient of species k as a reactant in -% reaction i. -% -% nu = stoich_r(a, species, rxns) -% -% Returns a sparse matrix the same size as above, but -% containing only entries for the specified species and -% reactions. For example, stoich_r(a,3,[1 3 5 7]) returns a -% sparse matrix containing only the coefficients for species 3 -% in reactions 1, 3, 5, and 7. -% -% See also: stoich_p, stoich_net. +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the reactant stoichiometric coefficients are desired. +% :param species: +% Species indices for which reactant stoichiometric coefficients +% should be retrieved. Optional argument; if specified, ``rxns`` +% must be specified as well. +% :param rxns: +% Reaction indices for which reactant stoichiometric coefficients +% should be retrieved. Optional argument; if specified, ``species`` +% must be specified as well. +% :return: +% Returns a sparse matrix of all reactant stoichiometric +% coefficients. The matrix element ``nu(k,i)`` is the +% stoichiometric coefficient of species k as a reactant in +% reaction i. If ``species`` and ``rxns`` are specified, the matrix +% will contain only entries for the specified species and +% reactions. For example, ``stoich_r(a,3,[1 3 5 7])`` returns a +% sparse matrix containing only the coefficients for species 3 +% in reactions 1, 3, 5, and 7. % + nsp = nTotalSpecies(a); nr = nReactions(a); b = sparse(nsp, nr); diff --git a/interfaces/matlab/toolbox/@Kinetics/ydot.m b/interfaces/matlab/toolbox/@Kinetics/ydot.m index f60cc858b..548818e2d 100644 --- a/interfaces/matlab/toolbox/@Kinetics/ydot.m +++ b/interfaces/matlab/toolbox/@Kinetics/ydot.m @@ -1,4 +1,14 @@ function v = ydot(a) -% YDOT - Evaluates wdot_k M_k / (density) +% YDOT Get the mass production rates of the species. +% v = ydot(a) +% Evaluates the source term :math:`\dot{\omega}_k M_k /\rho` % +% :param a: +% Instance of class :mat:func:`Kinetics` (or another +% object deriving from Kinetics) +% for which the ydots are desired. +% :return: +% Returns a vector of length nSpecies. Units: kg/s +% + v = kinetics_get(a.id, 24, 0); diff --git a/interfaces/matlab/toolbox/@Mixture/Mixture.m b/interfaces/matlab/toolbox/@Mixture/Mixture.m index 516931c8f..2f81cd8bf 100644 --- a/interfaces/matlab/toolbox/@Mixture/Mixture.m +++ b/interfaces/matlab/toolbox/@Mixture/Mixture.m @@ -1,33 +1,38 @@ function m = Mixture(phases) +% MIXTURE Multiphase mixture class constructor. +% m = Mixture(phases) +% Class :mat:func:`Mixture` represents mixtures of one or more phases of matter. +% To construct a mixture, supply a cell array of phases and +% mole numbers:: % -% MIXTURE - Multiphase mixtures. +% >> gas = importPhase('gas.cti'); +% >> graphite = importPhase('graphite.cti'); +% >> mix = Mixture({gas, 1.0; graphite, 0.1}); % -% Class Mixture represents -% mixtures of one or more phases of matter. To construct a mixture, -% supply a cell array of phases and mole numbers: +% Phases may also be added later using the addPhase method:: % -% >> gas = importPhase('gas.cti'); -% >> graphite = importPhase('graphite.cti'); -% >> mix = Mixture({gas, 1.0; graphite, 0.1}); +% >> water = importPhase('water.cti'); +% >> addPhase(mix, water, 3.0); % -% Phases may also be added later using the addPhase method: +% Note that the objects representing each phase compute only the +% intensive state of the phase - they do not store any information +% on the amount of this phase. Mixture objects, on the other hand, +% represent the full extensive state. % -% >> water = importPhase('water.cti'); -% >> addPhase(mix, water, 3.0); +% Mixture objects are 'lightweight' in the sense that they do not +% store parameters needed to compute thermodynamic or kinetic +% properties of the phases. These are contained in the +% ('heavyweight') phase objects. Multiple mixture objects may be +% constructed using the same set of phase objects. Each one stores +% its own state information locally, and synchronizes the phase +% objects whenever it requires phase properties. % -% Note that the objects representing each phase compute only the -% intensive state of the phase -- they do not store any information -% on the amount of this phase. Mixture objects, on the other hand, -% represent the full extensive state. -% -% Mixture objects are 'lightweight' in the sense that they do not -% store parameters needed to compute thermodynamic or kinetic -% properties of the phases. These are contained in the -% ('heavyweight') phase objects. Multiple mixture objects may be -% constructed using the same set of phase objects. Each one stores -% its own state information locally, and synchronizes the phase -% objects whenever it requires phase properties. +% :param phases: +% Cell array of phases and mole numbers +% :return: +% Instance of class :mat:func:`Mixture` % + if nargin > 1 error('Mixture: wrong number of arguments'); end diff --git a/interfaces/matlab/toolbox/@Mixture/addPhase.m b/interfaces/matlab/toolbox/@Mixture/addPhase.m index fd0b722fd..85ce277fb 100644 --- a/interfaces/matlab/toolbox/@Mixture/addPhase.m +++ b/interfaces/matlab/toolbox/@Mixture/addPhase.m @@ -1,9 +1,16 @@ function addPhase(self, phase, moles) -% ADDPHASE - Add a phase to the mixture. -% -% carbon = importPhase('graphite.cti'); -% addPhase(mix, carbon, 1.0); +% ADDPHASE Add a phase to a mixture. +% addPhase(self, phase, moles) +% :param self: +% Instance of class :mat:func:`Mixture` to which phases should be +% added +% :param phase: +% Instance of class :mat:func:`ThermoPhase` which should be added +% :param moles: +% Number of moles of the ``phase`` to be added to this mixture. +% Units: kmol % + if ~isa(phase,'ThermoPhase') error('Phase object of wrong type.'); end diff --git a/interfaces/matlab/toolbox/@Mixture/chemPotentials.m b/interfaces/matlab/toolbox/@Mixture/chemPotentials.m index ef5bac934..81abe6d4a 100644 --- a/interfaces/matlab/toolbox/@Mixture/chemPotentials.m +++ b/interfaces/matlab/toolbox/@Mixture/chemPotentials.m @@ -1,3 +1,10 @@ function mu = chemPotentials(self) -% CHEMPOTENTIALS - Chemical potentials of all species in all phases +% CHEMPOTENTIALS Get the chemical potentials of species in a mixture. +% mu = chemPotentials(self) +% :param self: +% Instance of class :mat:func:`Mixture` +% :return: +% Vector of chemical potentials. Units: J/kmol +% + mu = mixturemethods(41, mix_hndl(self)); diff --git a/interfaces/matlab/toolbox/@Mixture/display.m b/interfaces/matlab/toolbox/@Mixture/display.m index f911950b1..ebd235a07 100644 --- a/interfaces/matlab/toolbox/@Mixture/display.m +++ b/interfaces/matlab/toolbox/@Mixture/display.m @@ -1,4 +1,10 @@ function display(self) +% DISPLAY Display the state of the mixture on the terminal. +% display(self) +% :param self: +% Instance of class :mat:func:`Mixture` +% + [np nc] = size(self.phases); for n = 1:np s = [sprintf('\n******************* Phase %d', n) ... diff --git a/interfaces/matlab/toolbox/@Mixture/elementIndex.m b/interfaces/matlab/toolbox/@Mixture/elementIndex.m index 550b1eeea..5a08124f5 100644 --- a/interfaces/matlab/toolbox/@Mixture/elementIndex.m +++ b/interfaces/matlab/toolbox/@Mixture/elementIndex.m @@ -1,4 +1,12 @@ function n = elementIndex(self, name) -% ELEMENTINDEX - index of element with name 'name' +% ELEMENTINDEX Get the index of an element. +% n = elementIndex(self, name) +% :param self: +% Instance of class :mat:func:`Mixture` +% :param name: +% Name of the element whose index is desired +% :return: +% Index of element with name ``name`` % + n = mixturemethods(22, mix_hndl(self), name); diff --git a/interfaces/matlab/toolbox/@Mixture/equilibrate.m b/interfaces/matlab/toolbox/@Mixture/equilibrate.m index 0c7912739..72cef0839 100644 --- a/interfaces/matlab/toolbox/@Mixture/equilibrate.m +++ b/interfaces/matlab/toolbox/@Mixture/equilibrate.m @@ -1,43 +1,48 @@ function r = equilibrate(self, XY, err, maxsteps, maxiter, loglevel) +% EQUILIBRATE Set the mixture to a state of chemical equilibrium. +% r = equilibrate(self, XY, err, maxsteps, maxiter, loglevel) +% This method uses a version of the VCS algorithm to find the +% composition that minimizes the total Gibbs free energy of the +% mixture, subject to element conservation constraints. For a +% description of the theory, see Smith and Missen, "Chemical +% Reaction Equilibrium." The VCS algorithm is implemented in +% Cantera kernel class MultiPhaseEquil. % -% EQUILIBRATE - Set the mixture to a state of chemical equilibrium. +% The VCS algorithm solves for the equilibrium composition for +% specified temperature and pressure. If any other property pair +% other than "TP" is specified, then an outer iteration loop is +% used to adjust T and/or P so that the specified property +% values are obtained. :: % -% This method uses a version of the VCS algorithm to find the -% composition that minimizes the total Gibbs free energy of the -% mixture, subject to element conservation constraints. For a -% description of the theory, see Smith and Missen, "Chemical -% Reaction Equilibrium." The VCS algorithm is implemented in -% Cantera kernel class MultiPhaseEquil. +% >> equilibrate(mix, 'TP') +% >> equilibrate('TP', 1.0e-6, 500) % -% The VCS algorithm solves for the equilibrium composition for -% specified temperature and pressure. If any other property pair -% other than "TP" is specified, then an outer iteration loop is -% used to adjust T and/or P so that the specified property -% values are obtained. -% -% XY - Two-letter string specifying the two properties to hold -% fixed. Currently, 'TP', 'HP', and 'SP' are -% implemented. Default: 'TP'. -% -% err - Error tolerance. Iteration will continue until (Delta -% mu)/RT is less than this value for each reaction. Default: -% 1.0e-9. Note that this default is very conservative, and good -% equilibrium solutions may be obtained with larger error -% tolerances. -% -% maxsteps - Maximum number of steps to take while solving the -% equilibrium problem for specified T and P. Default: 1000. -% -% maxiter - Maximum number of temperature and/or pressure -% iterations. This is only relevant if a property pair other -% than (T,P) is specified. Default: 200. -% -% loglevel -- set to a value > 0 to write diagnostic output. -% Larger values generate more detailed information. -% -% >> equilibrate(mix, 'TP') -% >> equilibrate('TP', 1.0e-6, 500) +% :param self: +% Instance of class :mat:func:`Mixture` +% :param XY: +% Two-letter string specifying the two properties to hold +% fixed. Currently, ``'TP'``, ``'HP'``, ``'TV'``, and ``'SP'`` are +% implemented. Default: ``'TP'``. +% :param err: +% Error tolerance. Iteration will continue until :math:`\Delta\mu)/RT` +% is less than this value for each reaction. Default: +% 1.0e-9. Note that this default is very conservative, and good +% equilibrium solutions may be obtained with larger error +% tolerances. +% :param maxsteps: +% Maximum number of steps to take while solving the +% equilibrium problem for specified T and P. Default: 1000. +% :param maxiter: +% Maximum number of temperature and/or pressure +% iterations. This is only relevant if a property pair other +% than (T,P) is specified. Default: 200. +% :param loglevel: +% Set to a value > 0 to write diagnostic output. +% Larger values generate more detailed information. +% :return: +% The error in the solution % + if nargin < 6 loglevel = 0; end diff --git a/interfaces/matlab/toolbox/@Mixture/mix_hndl.m b/interfaces/matlab/toolbox/@Mixture/mix_hndl.m index 5a1436ca7..034bd5c40 100644 --- a/interfaces/matlab/toolbox/@Mixture/mix_hndl.m +++ b/interfaces/matlab/toolbox/@Mixture/mix_hndl.m @@ -1,4 +1,10 @@ function i = mix_hndl(self) -% MIX_HNDL - integer used to access kernel object +% MIX_HNDL Get the integer used to access the kernel object. +% i = mix_hndl(self) +% :param self: +% Instance of :mat:func:`Mixture` +% :return: +% Integer used to access the kernel object % + i = self.mixindex; diff --git a/interfaces/matlab/toolbox/@Mixture/nElements.m b/interfaces/matlab/toolbox/@Mixture/nElements.m index 2a967de9b..b1511c36c 100644 --- a/interfaces/matlab/toolbox/@Mixture/nElements.m +++ b/interfaces/matlab/toolbox/@Mixture/nElements.m @@ -1,4 +1,10 @@ function n = nElements(self) -% NELEMENTS - number of elements +% NELEMENTS Get the number of elements in a mixture. +% n = nElements(self) +% :param self: +% Instance of class :mat:func:`Mixture` +% :return: +% Number of elements in the input % + n = mixturemethods(21, mix_hndl(self)); diff --git a/interfaces/matlab/toolbox/@Mixture/nPhases.m b/interfaces/matlab/toolbox/@Mixture/nPhases.m index 04803a7fb..0ca06044e 100644 --- a/interfaces/matlab/toolbox/@Mixture/nPhases.m +++ b/interfaces/matlab/toolbox/@Mixture/nPhases.m @@ -1,4 +1,10 @@ function n = nPhases(self) -% NPHASES - number of phases +% NPHASES Get the number of phases in a mixture. +% n = nPhases(self) +% :param self: +% Instance of class :mat:func:`Mixture` +% :return: +% Number of phases in the input % + n = mixturemethods(19, mix_hndl(self)); diff --git a/interfaces/matlab/toolbox/@Mixture/nSpecies.m b/interfaces/matlab/toolbox/@Mixture/nSpecies.m index 989d44077..ec618fb8c 100644 --- a/interfaces/matlab/toolbox/@Mixture/nSpecies.m +++ b/interfaces/matlab/toolbox/@Mixture/nSpecies.m @@ -1,4 +1,10 @@ function n = nSpecies(self) -% NSPECIES - number of species +% NSPECIES Get the number of species in a mixture. +% n = nSpecies(self) +% :param self: +% Instance of class :mat:func:`Mixture` +% :return: +% Number of species in the input % + n = mixturemethods(24, mix_hndl(self)); diff --git a/interfaces/matlab/toolbox/@Mixture/phaseMoles.m b/interfaces/matlab/toolbox/@Mixture/phaseMoles.m index cb122004b..8a887d094 100644 --- a/interfaces/matlab/toolbox/@Mixture/phaseMoles.m +++ b/interfaces/matlab/toolbox/@Mixture/phaseMoles.m @@ -1,6 +1,14 @@ function moles = phaseMoles(self, n) -% PHASEMOLES - moles of phase number 'n' (kmol). +% PHASEMOLES Get the number of moles of a phase in a mixture. +% moles = phaseMoles(self, n) +% :param self: +% Instance of class :mat:func:`Mixture` +% :param n: +% Integer phase number in the input +% :return: +% Moles of phase number ``n``. Units: kmol % + if nargin == 2 moles = mixturemethods(28, mix_hndl(self), n); elseif nargin == 1 diff --git a/interfaces/matlab/toolbox/@Mixture/pressure.m b/interfaces/matlab/toolbox/@Mixture/pressure.m index 2ce951ed3..ca516992e 100644 --- a/interfaces/matlab/toolbox/@Mixture/pressure.m +++ b/interfaces/matlab/toolbox/@Mixture/pressure.m @@ -1,5 +1,10 @@ function p = pressure(self) -% PRESSURE - pressure (Pa) +% PRESSURE Get the pressure of the mixture. +% p = pressure(self) +% :param self: +% Instance of class :mat:func:`Mixture` +% :return: +% Pressure. Units: Pa % p = mixturemethods(26, mix_hndl(self)); diff --git a/interfaces/matlab/toolbox/@Mixture/setPhaseMoles.m b/interfaces/matlab/toolbox/@Mixture/setPhaseMoles.m index 70b494d79..4a66e7a43 100644 --- a/interfaces/matlab/toolbox/@Mixture/setPhaseMoles.m +++ b/interfaces/matlab/toolbox/@Mixture/setPhaseMoles.m @@ -1,5 +1,12 @@ function setPhaseMoles(self, n, moles) -% SETPHASEMOLES - set the number of moles of phase number 'n' to -% 'moles' (kmol). +% SETPHASEMOLES Set the number of moles of a phase in a mixture. +% setPhaseMoles(self, n, moles) +% :param self: +% Instance of class :mat:func:`Mixture` +% :param n: +% Phase number in the input +% :param moles: +% Number of moles to add. Units: kmol % + mixturemethods(7, mix_hndl(self), n, moles); diff --git a/interfaces/matlab/toolbox/@Mixture/setPressure.m b/interfaces/matlab/toolbox/@Mixture/setPressure.m index d3a586e7d..6f37fc878 100644 --- a/interfaces/matlab/toolbox/@Mixture/setPressure.m +++ b/interfaces/matlab/toolbox/@Mixture/setPressure.m @@ -1,4 +1,10 @@ function setPressure(self, P) -% SETPRESSURE - set the mixture pressure (Pa) +% SETPRESSURE Set the pressure of the mixture. +% setPressure(self, P) +% :param self: +% Instance of class :mat:func:`Mixture` +% :param P: +% Pressure. Units: Pa % + mixturemethods(6, mix_hndl(self), P); diff --git a/interfaces/matlab/toolbox/@Mixture/setSpeciesMoles.m b/interfaces/matlab/toolbox/@Mixture/setSpeciesMoles.m index 15383475e..85513ce78 100644 --- a/interfaces/matlab/toolbox/@Mixture/setSpeciesMoles.m +++ b/interfaces/matlab/toolbox/@Mixture/setSpeciesMoles.m @@ -1,10 +1,18 @@ function setSpeciesMoles(self, moles) -% SETSPECIESMOLES - Set the moles of the species [kmol]. The moles may -% be specified either as a string, or as an array. If an array is +% SETSPECIESMOLES Set the moles of the species. +% setSpeciesMoles(self, moles) +% Set the moles of the species in kmol. The moles may +% be specified either as a string, or as an vector. If a vector is % used, it must be dimensioned at least as large as the total number % of species in the mixture. Note that the species may belong to any -% phase, and unspecified species are set to zero. +% phase, and unspecified species are set to zero. :: % % >> setSpeciesMoles(mix, 'C(s):1.0, CH4:2.0, O2:0.2'); % +% :param self: +% Instance of class :mat:func:`Mixture` +% :param moles: +% Vector or string specifying the moles of species +% + mixturemethods(8, mix_hndl(self), moles); diff --git a/interfaces/matlab/toolbox/@Mixture/setTemperature.m b/interfaces/matlab/toolbox/@Mixture/setTemperature.m index c0e0e726e..81fc67516 100644 --- a/interfaces/matlab/toolbox/@Mixture/setTemperature.m +++ b/interfaces/matlab/toolbox/@Mixture/setTemperature.m @@ -1,4 +1,10 @@ function setTemperature(self, T) -% SETTEMPERATURE - set the mixture temperature +% SETTEMPERATURE Set the mixture temperature. +% setTemperature(self, T) +% :param self: +% Instance of class :mat:func:`Mixture` +% :param T: +% Temperature. Units: K % + mixturemethods(5, mix_hndl(self), T); diff --git a/interfaces/matlab/toolbox/@Mixture/speciesIndex.m b/interfaces/matlab/toolbox/@Mixture/speciesIndex.m index e8ea3837d..b74a1edc6 100644 --- a/interfaces/matlab/toolbox/@Mixture/speciesIndex.m +++ b/interfaces/matlab/toolbox/@Mixture/speciesIndex.m @@ -1,4 +1,12 @@ function n = speciesIndex(self, k, p) -% SPECIESINDEX - index of species with name 'name' +% SPECIESINDEX Get the index of a species in a mixture. +% n = speciesIndex(self, k, p) +% :param self: +% Instance of class :mat:func:`Mixture` +% :param name: +% Name of the speces whose index is desired +% :return: +% Index of species with name ``name`` % + n = mixturemethods(23, mix_hndl(self), k, p); diff --git a/interfaces/matlab/toolbox/@Mixture/temperature.m b/interfaces/matlab/toolbox/@Mixture/temperature.m index 23cf32705..dfa62727e 100644 --- a/interfaces/matlab/toolbox/@Mixture/temperature.m +++ b/interfaces/matlab/toolbox/@Mixture/temperature.m @@ -1,5 +1,10 @@ function t = temperature(self) -% TEMPERATURE - temperature (K) +% TEMPERATURE Get the temperature of a mixture. +% t = temperature(self) +% :param self: +% Instance of class :mat:func:`Mixture` +% :return: +% Temperature (K) % t = mixturemethods(25, mix_hndl(self)); diff --git a/interfaces/matlab/toolbox/@Reactor/Reactor.m b/interfaces/matlab/toolbox/@Reactor/Reactor.m index 9ec89f229..f550336c8 100644 --- a/interfaces/matlab/toolbox/@Reactor/Reactor.m +++ b/interfaces/matlab/toolbox/@Reactor/Reactor.m @@ -1,16 +1,36 @@ function x = Reactor(contents, typ) -% REACTOR - Create a Reactor object. +% REACTOR Reactor class constructor. +% x = Reactor(contents, typ) +% A :mat:func:`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. % -% 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. +% .. code-block:: matlab % -% r1 = Reactor % an empty reactor -% r2 = Reactor(gas) % a reactor containing a gas +% >> r1 = Reactor % an empty reactor +% >> r2 = Reactor(gas) % a reactor containing a phase % -% See also: Reservoir +% See also: :mat:func:`Reservoir`, :mat:func:`IdealGasReactor`, +% :mat:func:`IdealGasConstPressureReactor`, :mat:func:`ConstPressureReactor` % +% :param contents: +% Instance of class :mat:func:`Solution` or :mat:func:`Mixture` +% representing the contents of the reactor +% :param 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 +% +% :return: +% Instance of class :mat:func:`Reactor` +% + if nargin == 0 contents = 0; typ = 2; diff --git a/interfaces/matlab/toolbox/@Reactor/clear.m b/interfaces/matlab/toolbox/@Reactor/clear.m index 89f15641a..2b97d19cd 100644 --- a/interfaces/matlab/toolbox/@Reactor/clear.m +++ b/interfaces/matlab/toolbox/@Reactor/clear.m @@ -1,4 +1,8 @@ function clear(r) -% CLEAR - +% CLEAR Clear a reactor from memory. +% clear(r) +% :param f: +% Instance of :mat:func:`Reactor` to be cleared. % + reactormethods(2, reactor_hndl(r)); diff --git a/interfaces/matlab/toolbox/@Reactor/density.m b/interfaces/matlab/toolbox/@Reactor/density.m index 5f7de3cf4..a31b9b4d7 100644 --- a/interfaces/matlab/toolbox/@Reactor/density.m +++ b/interfaces/matlab/toolbox/@Reactor/density.m @@ -1,4 +1,10 @@ function rho = density(r) -% DENSITY - density +% DENSITY Get the density of the reactor. +% rho = density(r) +% :param r: +% Instance of class :mat:func:`Reactor` +% :return: +% Density of the phase in the input. Units: kg/m**3 % + rho = reactormethods(25, reactor_hndl(r)); diff --git a/interfaces/matlab/toolbox/@Reactor/enthalpy_mass.m b/interfaces/matlab/toolbox/@Reactor/enthalpy_mass.m index ef1ac7b69..e5b7cd159 100644 --- a/interfaces/matlab/toolbox/@Reactor/enthalpy_mass.m +++ b/interfaces/matlab/toolbox/@Reactor/enthalpy_mass.m @@ -1,12 +1,15 @@ function h = enthalpy_mass(r) -% ENTHALPY_MASS - the specific enthalpy [J/kg]. +% ENTHALPY_MASS The specific enthalpy of the reactor. +% h = enthalpy_mass(r) % -% h = enthalpy_mass(r) +% See also: :mat:func:`intEnergy_mass` % -% returns the specific enthalpy of the reactor contents at the -% end of the last call to 'advance' or 'step.' -% -% See also: Reactor/intEnergy_mass, Reactor/entropy_mass, -% Reactor/enthalpy_mole +% :param r: +% Instance of class :mat:func:`Reactor` +% :return: +% The specific enthalpy of the reactor contents at the +% end of the last call to :mat:func:`advance` or :mat:func:`step`. +% The enthalpy is retrieved from the solution vector. Units: J/kg % + h = reactormethods(27, reactor_hndl(r)); diff --git a/interfaces/matlab/toolbox/@Reactor/hndl.m b/interfaces/matlab/toolbox/@Reactor/hndl.m index b11113862..591463309 100644 --- a/interfaces/matlab/toolbox/@Reactor/hndl.m +++ b/interfaces/matlab/toolbox/@Reactor/hndl.m @@ -1,4 +1,9 @@ function i = hndl(r) +% HNDL Get the integer used to access the kernel object. +% i = hndl(r) +% Integer used to access kernel objects. Deprecated in favor of +% :mat:func:`reactor_hndl`. +% warning('This function is deprecated in favor of reactor_hndl.m') i = r.index; diff --git a/interfaces/matlab/toolbox/@Reactor/insert.m b/interfaces/matlab/toolbox/@Reactor/insert.m index 1c4d978d8..34b0de5bd 100644 --- a/interfaces/matlab/toolbox/@Reactor/insert.m +++ b/interfaces/matlab/toolbox/@Reactor/insert.m @@ -1,6 +1,12 @@ function insert(r, gas) -% INSERT - insert a mixture into the reactor +% INSERT Insert a solution or mixture into a reactor. +% insert(r, gas) +% :param r: +% Instance of class :mat:func:`Reactor` +% :param gas: +% Instance of class :mat:func:`Solution` to be inserted % + r.contents = gas; setThermoMgr(r, gas); setKineticsMgr(r, gas); diff --git a/interfaces/matlab/toolbox/@Reactor/intEnergy_mass.m b/interfaces/matlab/toolbox/@Reactor/intEnergy_mass.m index f5f01270b..bfb35c192 100644 --- a/interfaces/matlab/toolbox/@Reactor/intEnergy_mass.m +++ b/interfaces/matlab/toolbox/@Reactor/intEnergy_mass.m @@ -1,12 +1,15 @@ function u = intEnergy_mass(r) -% INTENERGY_MASS - the specific internal energy [J/kg]. +% INTENERGY_MASS Get the specific internal energy. +% u = intEnergy_mass(r) +% See also: :mat:func:`enthalpy_mass` % -% u = intEnergy_mass(r) -% -% returns the specific internal energy of the reactor contents at -% the end of the last call to 'advance' or 'step.' -% -% See also: Reactor/enthalpy_mass, Reactor/entropy_mass, -% Reactor/enthalpy_mole +% :param r: +% Instance of class :mat:func:`Reactor` +% :return: +% The specific internal energy of the reactor contents at the +% end of the last call to :mat:func:`advance` or :mat:func:`step`. +% The internal energy is retrieved from the solution vector. +% Units: J/kg % + u = reactormethods(28, reactor_hndl(r)); diff --git a/interfaces/matlab/toolbox/@Reactor/mass.m b/interfaces/matlab/toolbox/@Reactor/mass.m index 52f274b46..21b60026a 100644 --- a/interfaces/matlab/toolbox/@Reactor/mass.m +++ b/interfaces/matlab/toolbox/@Reactor/mass.m @@ -1,4 +1,12 @@ function m = mass(r) -% MASS - +% MASS Get the mass of the reactor. +% m = mass(r) +% :param r: +% Instance of class :mat:func:`Reactor` +% :return: +% The mass of the reactor contents at the +% end of the last call to :mat:func:`advance` or :mat:func:`step`. +% The mass is retrieved from the solution vector. Units: kg % + m = reactormethods(23, reactor_hndl(r)); diff --git a/interfaces/matlab/toolbox/@Reactor/massFraction.m b/interfaces/matlab/toolbox/@Reactor/massFraction.m index 005627fa7..99abb9177 100644 --- a/interfaces/matlab/toolbox/@Reactor/massFraction.m +++ b/interfaces/matlab/toolbox/@Reactor/massFraction.m @@ -1,5 +1,13 @@ function y = massFraction(r, species) -% MASSFRACTION - Mass fraction of species with name 'species'. +% MASSFRACTION Get the mass fraction of a species. +% y = massFraction(r, species) +% :param r: +% Instance of class :mat:func:`Reactor` +% :param species: +% String or the one-based integer index of the species +% :return: +% The mass fraction of the specifed species in the reactor at the +% end of the last call to :mat:func:`advance` or :mat:func:`step`. % if ischar(species) diff --git a/interfaces/matlab/toolbox/@Reactor/massFractions.m b/interfaces/matlab/toolbox/@Reactor/massFractions.m index e5aea925d..b550819d1 100644 --- a/interfaces/matlab/toolbox/@Reactor/massFractions.m +++ b/interfaces/matlab/toolbox/@Reactor/massFractions.m @@ -1,7 +1,13 @@ function y = massFractions(r) -% MASSFRACTION - Mass fractions of reactor contents after last call -% to 'advance' or 'step'. +% MASSFRACTIONS Get the mass fractions of the species. +% y = massFractions(r) +% :param r: +% Instance of class :mat:func:`Reactor` +% :return: +% The mass fractions of the reactor contents at the +% end of the last call to :mat:func:`advance` or :mat:func:`step`. % + nsp = nSpecies(r.contents); ir = reactor_hndl(r); y = zeros(1, nsp); diff --git a/interfaces/matlab/toolbox/@Reactor/pressure.m b/interfaces/matlab/toolbox/@Reactor/pressure.m index 1e262ec0b..d7e021fb4 100644 --- a/interfaces/matlab/toolbox/@Reactor/pressure.m +++ b/interfaces/matlab/toolbox/@Reactor/pressure.m @@ -1,4 +1,12 @@ function p = pressure(r) -% PRESSURE - pressure +% PRESSURE Get the pressure of the reactor. +% p = pressure(r) +% :param r: +% Instance of class :mat:func:`Reactor` +% :return: +% The pressure of the reactor contents at the +% end of the last call to :mat:func:`advance` or :mat:func:`step`. +% Units: Pa % + p = reactormethods(29, reactor_hndl(r)); diff --git a/interfaces/matlab/toolbox/@Reactor/reactor_hndl.m b/interfaces/matlab/toolbox/@Reactor/reactor_hndl.m index aa39d5350..5b3b9a5cb 100644 --- a/interfaces/matlab/toolbox/@Reactor/reactor_hndl.m +++ b/interfaces/matlab/toolbox/@Reactor/reactor_hndl.m @@ -1,2 +1,11 @@ function i = reactor_hndl(r) +% REACTOR_HNDL Get the integer used to access the kernel object. +% i = reactor_hndl(r) +% :param r: +% Instance of class :mat:func:`Reactor` +% for which the handle is desired. +% :return: +% Integer used to access the kernel object +% + i = r.index; diff --git a/interfaces/matlab/toolbox/@Reactor/setEnergy.m b/interfaces/matlab/toolbox/@Reactor/setEnergy.m index 0545c2a67..80ef46849 100644 --- a/interfaces/matlab/toolbox/@Reactor/setEnergy.m +++ b/interfaces/matlab/toolbox/@Reactor/setEnergy.m @@ -1,16 +1,24 @@ function setEnergy(r, flag) -% SETENERGY - 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. +% SETENERGY Enable or disable solving the energy equation. +% setEnergy(r, flag) +% 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. +% energy equation for isothermal simulations. :: % -% >>> setEnergy(r, 'on'); -% >>> setEnergy(r, 'off'); +% >> setEnergy(r, 'on'); +% >> setEnergy(r, 'off'); % +% :param r: +% Instance of class :mat:func:`Reactor` +% :param flag: +% String, either ``'on'`` or ``'off`` to enable and disable +% solving the energy equation, respectively +% + iflag = -1; if strcmp(flag, {'on'}) iflag = 1; diff --git a/interfaces/matlab/toolbox/@Reactor/setInitialVolume.m b/interfaces/matlab/toolbox/@Reactor/setInitialVolume.m index 590b633db..d3df86258 100644 --- a/interfaces/matlab/toolbox/@Reactor/setInitialVolume.m +++ b/interfaces/matlab/toolbox/@Reactor/setInitialVolume.m @@ -1,5 +1,10 @@ function setInitialVolume(r, v0) -% SETINITIALVOLUME - +% SETINITIALVOLUME Set the initial reactor volume. +% setInitialVolume(r, v0) +% :param r: +% Instance of class :mat:func:`Reactor` +% :param v0: +% Initial volume. Units: m**3 % reactormethods(4, reactor_hndl(r), v0); diff --git a/interfaces/matlab/toolbox/@Reactor/setKineticsMgr.m b/interfaces/matlab/toolbox/@Reactor/setKineticsMgr.m index 873e6f661..d74a814a0 100644 --- a/interfaces/matlab/toolbox/@Reactor/setKineticsMgr.m +++ b/interfaces/matlab/toolbox/@Reactor/setKineticsMgr.m @@ -1,10 +1,18 @@ function setKineticsMgr(r, k) -% SETKINETICSMGR - set the kinetics manager. This method is used -% internally during Reactor initialization, but is usually not -% called by users. +% SETKINETICSMGR Set the kinetics manager. +% setKineticsMgr(r, k) +% This method is used internally during Reactor initialization, but +% is usually not called by users. % -if ~isa(k,'Kinetics') - error('wrong object type'); +% :param r: +% Instance of class :mat:func:`Reactor` +% :param k: +% Instance of class :mat:func:`Kinetics`, or another object +% containing an instance of that class. +% + +if ~isa(k, 'Kinetics') + error('Wrong object type.'); end reactormethods(7, reactor_hndl(r), kinetics_hndl(k)); diff --git a/interfaces/matlab/toolbox/@Reactor/setMassFlowRate.m b/interfaces/matlab/toolbox/@Reactor/setMassFlowRate.m index b6411f685..83bd52c16 100644 --- a/interfaces/matlab/toolbox/@Reactor/setMassFlowRate.m +++ b/interfaces/matlab/toolbox/@Reactor/setMassFlowRate.m @@ -1,4 +1,10 @@ function setMassFlowRate(r, mdot) -% SETMASSFLOWRATE - +% SETMASSFLOWRATE Set the mass flow rate. +% setMassFlowRate(r, mdot) +% :param r: +% Instance of class :mat:func:`Reactor` +% :param mdot: +% Mass flow rate. Units: kg/s % + reactormethods(10, reactor_hndl(r), mdot); diff --git a/interfaces/matlab/toolbox/@Reactor/setThermoMgr.m b/interfaces/matlab/toolbox/@Reactor/setThermoMgr.m index ab07272ca..b6f7e4d77 100644 --- a/interfaces/matlab/toolbox/@Reactor/setThermoMgr.m +++ b/interfaces/matlab/toolbox/@Reactor/setThermoMgr.m @@ -1,6 +1,16 @@ function setThermoMgr(r, t) -% SETTHERMOMGR - set the thermo manager +% SETTHERMOMGR Set the thermodynamics manager. +% setThermoMgr(r, t) +% This method is used internally during Reactor initialization, but +% is usually not called by users. % +% :param r: +% Instance of class :mat:func:`Reactor` +% :param t: +% Instance of class :mat:func:`ThermoPhase`, or another object +% containing an instance of that class. +% + if ~isa(t,'ThermoPhase') error('wrong object type'); end diff --git a/interfaces/matlab/toolbox/@Reactor/temperature.m b/interfaces/matlab/toolbox/@Reactor/temperature.m index e99ccaebc..9071415f4 100644 --- a/interfaces/matlab/toolbox/@Reactor/temperature.m +++ b/interfaces/matlab/toolbox/@Reactor/temperature.m @@ -1,4 +1,12 @@ function t = temperature(r) -% TEMPERATURE - temperature +% TEMPERATURE Get the temperature of the reactor. +% t = temperature(r) +% :param r: +% Instance of class :mat:func:`Reactor` +% :return: +% The temperature of the reactor contents at the +% end of the last call to :mat:func:`advance` or :mat:func:`step`. +% Units: K % + t = reactormethods(26, reactor_hndl(r)); diff --git a/interfaces/matlab/toolbox/@Reactor/volume.m b/interfaces/matlab/toolbox/@Reactor/volume.m index aa2b15906..a7b5c308e 100644 --- a/interfaces/matlab/toolbox/@Reactor/volume.m +++ b/interfaces/matlab/toolbox/@Reactor/volume.m @@ -1,4 +1,12 @@ function v = volume(r) -% VOLUME - volume +% VOLUME Get the volume of the reactor. +% v = volume(r) +% :param r: +% Instance of class :mat:func:`Reactor` +% :return: +% The volume of the reactor contents at the +% end of the last call to :mat:func:`advance` or :mat:func:`step`. +% Units: m**3 % + v = reactormethods(24, reactor_hndl(r)); diff --git a/interfaces/matlab/toolbox/@ReactorNet/ReactorNet.m b/interfaces/matlab/toolbox/@ReactorNet/ReactorNet.m index f3fd4b293..1f4ee6542 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/ReactorNet.m +++ b/interfaces/matlab/toolbox/@ReactorNet/ReactorNet.m @@ -1,8 +1,27 @@ function x = ReactorNet(reactors) -% REACTOR - Create a ReactorNet object. +% REACTORNET ReactorNet class constructor. +% x = ReactorNet(reactors) +% A :mat:func:`ReactorNet` object is a container that holds one +% or more :mat:func:`Reactor` objects in a network. :mat:func:`ReactorNet` +% objects are used to simultaneously advance the state of one or +% more coupled reactors. % -% A ReactorNet object is a container that holds one or more -% Reactor objects. +% Example:: +% +% >> r1 = Reactor(gas1) +% >> r2 = Reactor(gas2) +% >> <... install walls, inlets, outlets, etc...> +% +% >> reactor_network = ReactorNet({r1, r2}) +% >> advance(reactor_network, time) +% +% See also: :mat:func:`Reactor` +% +% :param reactors: +% A single instance of :mat:func:`Reactor` or a cell array +% of instances of :mat:func:`Reactor` +% :return: +% Instance of class :mat:func:`ReactorNet` % if nargin ~= 1 diff --git a/interfaces/matlab/toolbox/@ReactorNet/addReactor.m b/interfaces/matlab/toolbox/@ReactorNet/addReactor.m index b01a52147..1ab2078ad 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/addReactor.m +++ b/interfaces/matlab/toolbox/@ReactorNet/addReactor.m @@ -1,3 +1,10 @@ function addReactor(net, reactor) -% ADDREACTOR - Add a reactor to the network +% ADDREACTOR Add a reactor to a network. +% addReactor(net, reactor) +% :param net: +% Instance of class :mat:func:`ReactorNet` +% :param reactor: +% Instance of class :mat:func:`Reactor` +% + reactornetmethods(4, reactornet_hndl(net), reactor_hndl(reactor)); diff --git a/interfaces/matlab/toolbox/@ReactorNet/advance.m b/interfaces/matlab/toolbox/@ReactorNet/advance.m index 1b59b6c99..cf51b334e 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/advance.m +++ b/interfaces/matlab/toolbox/@ReactorNet/advance.m @@ -1,22 +1,31 @@ function advance(n, tout) -% ADVANCE - Advance the state of the reactor network in time. +% ADVANCE Advance the state of the reactor network in time. +% advance(n, tout) +% Method :mat:func:`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. % -% 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. +% .. code-block:: matlab % -% for i in 1:10 -% tout = 0.1*i -% advance(n, tout) -% ... -% -% ... -% end +% for i in 1:10 +% tout = 0.1*i +% advance(n, tout) +% ... +% +% ... +% end % -% See also: ReactorNet/step +% See also: :mat:func:`step` % +% :param n: +% Instance of class :mat:func:`ReactorNet` +% :param tout: +% End time of the integration. The solver may take many internal +% time steps to reach ``tout``. +% + reactornetmethods(8, reactornet_hndl(n), tout); diff --git a/interfaces/matlab/toolbox/@ReactorNet/atol.m b/interfaces/matlab/toolbox/@ReactorNet/atol.m index f93415961..e995cd30b 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/atol.m +++ b/interfaces/matlab/toolbox/@ReactorNet/atol.m @@ -1,5 +1,11 @@ function t = atol(r) -% ATOL - absolute error tolerance +% ATOL Get the absolute error tolerance. +% t = atol(r) +% :param r: +% Instance of class :mat:func:`ReactorNet` +% :return: +% Absolute error tolerance. % + t = reactornetmethods(24, reactornet_hndl(r)); diff --git a/interfaces/matlab/toolbox/@ReactorNet/reactornet_hndl.m b/interfaces/matlab/toolbox/@ReactorNet/reactornet_hndl.m index f6230aded..00206c016 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/reactornet_hndl.m +++ b/interfaces/matlab/toolbox/@ReactorNet/reactornet_hndl.m @@ -1,2 +1,11 @@ function i = reactornet_hndl(r) +% REACTORNET_HNDL Get the integer used to access the kernel object. +% i = reactornet_hndl(r) +% :param r: +% Instance of class :mat:func:`ReactorNet` +% for which the handle is desired. +% :return: +% Integer used to access the kernel object. +% + i = r.index; diff --git a/interfaces/matlab/toolbox/@ReactorNet/rtol.m b/interfaces/matlab/toolbox/@ReactorNet/rtol.m index 22423698c..9478ddfe7 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/rtol.m +++ b/interfaces/matlab/toolbox/@ReactorNet/rtol.m @@ -1,4 +1,10 @@ function t = rtol(r) -% RTOL - relative error tolerance +% RTOL Get the relative error tolerance. +% t = rtol(r) +% :param r: +% Instance of class :mat:func:`ReactorNet` +% :return: +% Relative error tolerance. % + t = reactornetmethods(23, reactornet_hndl(r)); diff --git a/interfaces/matlab/toolbox/@ReactorNet/setInitialTime.m b/interfaces/matlab/toolbox/@ReactorNet/setInitialTime.m index 052fe71e2..414a5a398 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/setInitialTime.m +++ b/interfaces/matlab/toolbox/@ReactorNet/setInitialTime.m @@ -1,9 +1,15 @@ function setInitialTime(r, t) -% SETINITIALTIME - Set the initial time at which to begin the time -% integration. -% +% SETINITIALTIME Set the initial time of the integration. +% setInitialTime(r, t) % If the time integration has already begun, this restarts the % integrator using the current solution as the initial condition, -% setting the time to 't'. +% setting the time to ``t``. % +% :param r: +% Instance of class :mat:func:`ReactorNet` +% :param t: +% Time at which integration should be restarted, using the +% current state as the initial condition. Units: s +% + reactornetmethods(5, reactornet_hndl(r), t); diff --git a/interfaces/matlab/toolbox/@ReactorNet/setMaxTimeStep.m b/interfaces/matlab/toolbox/@ReactorNet/setMaxTimeStep.m index 8ae99c71c..3f6d23dd4 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/setMaxTimeStep.m +++ b/interfaces/matlab/toolbox/@ReactorNet/setMaxTimeStep.m @@ -1,6 +1,6 @@ function setMaxTimeStep(r, maxstep) -% SETMAXTIMESTEP - Set the maximum time step. -% +% SETMAXTIMESTEP Set the maximum time step. +% setMaxTimeStep(r, maxstep) % 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 @@ -9,4 +9,10 @@ function setMaxTimeStep(r, maxstep) % problems later. Use this method to set an upper bound on the % timestep. % +% :param r: +% Instance of class :mat:func:`ReactorNet` +% :param maxstep: +% Maximum time step +% + reactornetmethods(6, reactornet_hndl(r), maxstep); diff --git a/interfaces/matlab/toolbox/@ReactorNet/setTolerances.m b/interfaces/matlab/toolbox/@ReactorNet/setTolerances.m index 978fbf167..05ca2c9c2 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/setTolerances.m +++ b/interfaces/matlab/toolbox/@ReactorNet/setTolerances.m @@ -1,7 +1,10 @@ function setTolerances(r, rtol, atol) -% SETTOLERANCES - Set error tolerances. -% -% rtol - scalar relative error tolerance -% atol - scalar absolute error tolerance +% SETTOLERANCES Set the error tolerances. +% setTolerances(r, rtol, atol) +% :param rtol: +% Scalar relative error tolerance +% :param atol: +% Scalar absolute error tolerance % + reactornetmethods(7, reactornet_hndl(r), rtol, atol); diff --git a/interfaces/matlab/toolbox/@ReactorNet/step.m b/interfaces/matlab/toolbox/@ReactorNet/step.m index c5c86c670..9fcf384bf 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/step.m +++ b/interfaces/matlab/toolbox/@ReactorNet/step.m @@ -1,27 +1,40 @@ function t = step(r, tout) -% STEP - Take one internal time step toward tout. +% STEP Take one internal time step. +% t = step(r, tout) +% 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. % -% 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 :mat:func:`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. % -% Method 'step' takes one internal time step and returns. This -% can be useful when it is desired to resolve a rapidly-changing -% solution. +% This method can be used as follows: % -% This method can be used as follows: +% .. code-block:: matlab % -% t = 0.0 -% tout = 0.1 -% while t < tout -% t = step(r, tout) -% ,,, -% -% ... -% end +% t = 0.0 +% tout = 0.1 +% while t < tout +% t = step(r, tout) +% ,,, +% +% ... +% end % -% See also: Reactor/advance +% See also: :mat:func:`advance` % +% :param r: +% Instance of class :mat:func:`ReactorNet` +% :param tout: +% End time that the integrator should take one internal time +% step towards. This end time may not be reached, or may be +% exceeded by the internal time step. +% :return: +% Network time after the internal time step. Units: s +% + t = reactornetmethods(21, reactornet_hndl(r), tout); diff --git a/interfaces/matlab/toolbox/@ReactorNet/time.m b/interfaces/matlab/toolbox/@ReactorNet/time.m index e51f7253f..41e9896d9 100644 --- a/interfaces/matlab/toolbox/@ReactorNet/time.m +++ b/interfaces/matlab/toolbox/@ReactorNet/time.m @@ -1,4 +1,10 @@ function t = time(r) -% TIME - current value of the time. +% TIME Get the current value of the time. +% t = time(r) +% :param r: +% Instance of class :mat:func:`ReactorNet` +% :return: +% Current time in the input ReactorNet. Units: s % + t = reactornetmethods(22, reactornet_hndl(r)); diff --git a/interfaces/matlab/toolbox/@Solution/Solution.m b/interfaces/matlab/toolbox/@Solution/Solution.m index feb0cde0b..a1be8833f 100644 --- a/interfaces/matlab/toolbox/@Solution/Solution.m +++ b/interfaces/matlab/toolbox/@Solution/Solution.m @@ -1,31 +1,48 @@ function s = Solution(src, id, trans) -% SOLUTION - class Solution constructor. +% SOLUTION Solution class constructor. +% s = Solution(src, id, trans) +% Class :mat:func:`Solution` represents solutions of multiple species. A +% solution is defined as a mixture of two or more constituents +% (species) that are completely mixed on molecular length +% scales. The macroscopic intensive thermodynamic state of a +% solution is specified by two thermodynamic properties (for +% example, the temperature and pressure), and the relative amounts +% of each species, which may be given as mole fractions or mass +% fractions. :: % -% Class Solution represents solutions of multiple species. A -% solution is defined as a mixture of two or more constituents -% (species) that are completely mixed on molecular length -% scales. The macroscopic intensive thermodynamic state of a -% solution is specified by two thermodynamic properties (for -% example, the temperature and pressure), and the relative amounts -% of each species, which may be given as mole fractions or mass -% fractions. - -% s = Solution('input.xml', ) +% >> s = Solution('input.xml'[, phase_name[, transport_model]]) % -% constructs a Solution object from a specification contained in -% file input.xml, and using a specified transport property -% model. If the transport model is omitted, it defaults to -% 'None', which disables transport property evaluation. - -% Class Solution derives from three more basic classes, and most of -% its methods are inherited from these classes. These are: +% constructs a Solution object from a specification contained in +% file ``input.xml``. Optionally, the name of the phase to be imported +% can be specified with ``phase_name``. If a +% Transport model is included in ``input.xml``, it will be included +% in the Solution instance with the default transport modeling as set +% in the input file. To specify the transport modeling, set the input +% argument ``trans`` to one of ``'default'``, ``'Mix'``, or ``'Multi'``. +% In this case, the phase name must be specified as well. Alternatively, +% change the ``transport`` node in the CTML file, or ``transport`` +% property inthe CTI file before loading the phase. The transport +% modeling cannot be changed once the phase is loaded. % -% class ThermoPhase - composition information and -% thermodynamic properties -% class Kinetics - homogeneous kinetics -% class Transport - transport properties +% Class :mat:func:`Solution` derives from three more basic classes, and most of +% its methods are inherited from these classes. These are: % -% See also: ThermoPhase, Kinetics, Transport +% * class :mat:func:`ThermoPhase` - composition information and thermodynamic properties +% * class :mat:func:`Kinetics` - homogeneous kinetics +% * class :mat:func:`Transport` - transport properties +% +% See also: :mat:func:`ThermoPhase`, :mat:func:`Kinetics`, :mat:func:`Transport` +% +% :param src: +% Input string of CTI or CTML file name. +% :param id: +% Optional unless ``trans`` is specified. ID of the phase to +% import as specified in the CTML or CTI file. +% :param trans: +% String, transport modeling. Possible values are ``'default'``, +% ``'Mix'``, or ``'Multi'``. If not specified, ``'default'`` is used. +% :return: +% Instance of class :mat:func:`Solution` % doc = XML_Node('doc', src); if nargin == 1 diff --git a/interfaces/matlab/toolbox/@Solution/clear.m b/interfaces/matlab/toolbox/@Solution/clear.m index 777502203..65c4e8aee 100644 --- a/interfaces/matlab/toolbox/@Solution/clear.m +++ b/interfaces/matlab/toolbox/@Solution/clear.m @@ -1,6 +1,10 @@ function clear(s) -% CLEAR - Delete the kernel object. +% CLEAR Delete the kernel objects associated with a Solution. +% clear(s) +% :param s: +% Instance of class :mat:func:`Solution` % + clear(s.th); clear(s.kin); disp('Solution.clear: skipping clearing the transport object... check this!') diff --git a/interfaces/matlab/toolbox/@ThermoPhase/ThermoPhase.m b/interfaces/matlab/toolbox/@ThermoPhase/ThermoPhase.m index 8400e9a7a..2bcefdbe1 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/ThermoPhase.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/ThermoPhase.m @@ -1,6 +1,14 @@ function t = ThermoPhase(r) -%THERMOPHASE Cantera ThermoPhase class constructor +% THERMOPHASE ThermoPhase class constructor. +% t = ThermoPhase(r) +% :param r: +% If ``r`` is an instance of class :mat:func:`ThermoPhase`, +% a copy of the instance is returned. Otherwise, ``r`` must +% be an instance of class :mat:func:`XML_Node`. +% :return: +% Instance of class :mat:func:`ThermoPhase` % + if nargin == 1 if isa(r, 'ThermoPhase') % create a copy diff --git a/interfaces/matlab/toolbox/@ThermoPhase/atomicMasses.m b/interfaces/matlab/toolbox/@ThermoPhase/atomicMasses.m index 6791818b8..10d7a0dc0 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/atomicMasses.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/atomicMasses.m @@ -1,5 +1,11 @@ function x = atomicMasses(tp) -% ATOMICMASSES - Array of element atomic masses [kg/kmol]. +% ATOMICMASSES Get the atomic masses of the elements. +% x = atomicMasses(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase). +% :return: +% Vector of element atomic masses. Units: kg/kmol % x = phase_get(tp.tp_id, 30); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/chemPotentials.m b/interfaces/matlab/toolbox/@ThermoPhase/chemPotentials.m index ba4877636..2893a05d5 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/chemPotentials.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/chemPotentials.m @@ -1,5 +1,15 @@ function mu = chemPotentials(tp) -% CHEMPOTENTIALS - Species chemical potentials. +% CHEMPOTENTIALS Get the chemical potentials of the species. +% mu = chemPotentials(tp) +% The expressions used to compute the chemical potential +% depend on the model implemented by the underlying kernel +% thermo manager. +% +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase). +% :return: +% Vector of species chemical potentials. Units: J/kmol % % This method returns an array containing the species % chemical potentials [J/kmol]. The expressions used to diff --git a/interfaces/matlab/toolbox/@ThermoPhase/clear.m b/interfaces/matlab/toolbox/@ThermoPhase/clear.m index 0472ca9d2..c4655f873 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/clear.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/clear.m @@ -1,5 +1,9 @@ function clear(tp) -% CLEAR - Delete the kernel object. +% CLEAR Delete the kernel object. +% clear(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) % thermo_set(tp.tp_id, 0, 10); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/cp_R.m b/interfaces/matlab/toolbox/@ThermoPhase/cp_R.m index b7929dd7d..9b51b5edd 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/cp_R.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/cp_R.m @@ -1,8 +1,12 @@ function v = cp_R(tp) -% CP_R - Species non-dimensional heat capacities. -% -% This method returns an array containing the pure species -% standard-state heat capacities at constant pressure. +% CP_R Get the non-dimensional specific heats at constant pressure. +% v = cp_R(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of specific heats of the species at +% constant pressure, non-dimensional basis % v = thermo_get(tp.tp_id, 38); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/cp_mass.m b/interfaces/matlab/toolbox/@ThermoPhase/cp_mass.m index 1eed51397..a436361ec 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/cp_mass.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/cp_mass.m @@ -1,4 +1,12 @@ function v = cp_mass(tp) -% CP_MASS - Specific heat at constant pressure [J/kg-K]. +% CP_MASS Get the mass-basis specific heats at constant pressure. +% v = cp_mass(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of specific heats of the species at +% constant pressure. Units: J/kg-K +% v = thermo_get(tp.tp_id, 13); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/cp_mole.m b/interfaces/matlab/toolbox/@ThermoPhase/cp_mole.m index 6169ae252..c78cdc33e 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/cp_mole.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/cp_mole.m @@ -1,4 +1,12 @@ function v = cp_mole(tp) -% CP_MOLE - Molar heat capacity at constant pressure [J/kmol-K]. +% CP_MOLE Get the molar-basis specific heats at constant pressure. +% v = cp_mole(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of specific heats of the species at +% constant pressure. Units: J/kmol-K +% v = thermo_get(tp.tp_id, 6); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/critDensity.m b/interfaces/matlab/toolbox/@ThermoPhase/critDensity.m index 009448a5b..3c91208e1 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/critDensity.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/critDensity.m @@ -1,5 +1,11 @@ function v = critDensity(tp) -% CRITDENSITY - Critical density [kg/m3]. +% CRITDENSITY Get the critical density. +% v = critDensity(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Critical density. Units: kg/m**3 % v = thermo_get(tp.tp_id, 21); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/critPressure.m b/interfaces/matlab/toolbox/@ThermoPhase/critPressure.m index 717d3d3f4..1e07894c7 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/critPressure.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/critPressure.m @@ -1,5 +1,11 @@ function v = critPressure(tp) -% CRITPRESSURE - Critical pressure [Pa]. +% CRITPRESSURE Get the critical pressure. +% v = critPressure(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Critical pressure. Units: Pa % v = thermo_get(tp.tp_id, 20); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/critTemperature.m b/interfaces/matlab/toolbox/@ThermoPhase/critTemperature.m index 8bc3aa95a..17be99a7b 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/critTemperature.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/critTemperature.m @@ -1,5 +1,11 @@ function v = critTemperature(tp) -% CRITTEMPERATURE - Critical temperature [K]. +% CRITTEMPERATURE Get the critical temperature. +% v = critTemperature(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Critical temperature. Units: K % v = thermo_get(tp.tp_id, 19); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/cv_mass.m b/interfaces/matlab/toolbox/@ThermoPhase/cv_mass.m index 116767a7e..7268ed928 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/cv_mass.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/cv_mass.m @@ -1,4 +1,12 @@ function v = cv_mass(tp) -% CV_MASS - Specific heat at constant volume [J/kg-K]. +% CV_MASS Get the mass-basis specific heats at constant volume. +% v = cv_mass(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of specific heats of the species at +% constant volume. Units: J/kg-K +% v = thermo_get(tp.tp_id, 14); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/cv_mole.m b/interfaces/matlab/toolbox/@ThermoPhase/cv_mole.m index 82d59dbe2..9d6084539 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/cv_mole.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/cv_mole.m @@ -1,4 +1,12 @@ function v = cv_mole(tp) -% CV_MOLE - Molar heat capacity at constant volume [J/kmol-K]. +% CV_MOLE Get the molar-basis specific heats at constant volume. +% v = cv_mole(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of specific heats of the species at +% constant volume. Units: J/kmol-K +% v = thermo_get(tp.tp_id, 7); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/density.m b/interfaces/matlab/toolbox/@ThermoPhase/density.m index 6b1061f30..f7ed17117 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/density.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/density.m @@ -1,5 +1,11 @@ function rho = density(tp) -% DENSITY - Mass density [kg/m^3]. +% DENSITY Get the density. +% rho = density(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Mass density. Units: kg/m**3 % rho = phase_get(tp.tp_id, 2); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/electricPotential.m b/interfaces/matlab/toolbox/@ThermoPhase/electricPotential.m index e56aeea0f..ec5788de1 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/electricPotential.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/electricPotential.m @@ -1,5 +1,11 @@ function v = electricPotential(tp) -% ELECTRICPOTENTIAL - the electric potential of the phase +% ELECTRICPOTENTIAL Get the electric potential. +% v = electricPotential(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% The electric potential of the phase. Units: V % v = thermo_get(tp.tp_id, 25); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/elementIndex.m b/interfaces/matlab/toolbox/@ThermoPhase/elementIndex.m index ff0404fb8..60416550b 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/elementIndex.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/elementIndex.m @@ -1,22 +1,29 @@ function k = elementIndex(tp, name) -% ELEMENTINDEX - The element index of the element with name -% 'name'. +% ELEMENTINDEX Get the index of an element given its name. +% k = elementIndex(tp,name) +% The index is an integer assigned to each element in sequence as it +% is read in from the input file. % -% The index is an integer assigned to each element in sequence as it -% is read in from the input file. +% If ``name`` is a single string, the return value will be a integer +% containing the corresponding index. If it is an cell array of +% strings, the output will be an array of the same shape +% containing the indices. % -% If name is a single string, the return value will be a integer -% containing the corresponding index. If it is an cell array of -% strings, the output will be an array of the same shape -% containing the indices. +% NOTE: In keeping with the conventions used by Matlab, this method +% returns 1 for the first element. In contrast, the corresponding +% method elementIndex in the Cantera C++ and Python interfaces +% returns 0 for the first element, 1 for the second one, etc. :: % -% NOTE: In keeping with the conventions used by Matlab, this method -% returns 1 for the first element. In contrast, the corresponding -% method elementIndex in the Cantera C++ and Python interfaces -% returns 0 for the first element, 1 for the second one, etc. +% >> ic = elementIndex(gas, 'C'); +% >> ih = elementIndex(gas, 'H'); % -% ic = elementIndex(gas, 'C'); -% ih = elementIndex(gas, 'H'); +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :param name: +% String or cell array of strings of elements to look up +% :return: +% Integer or vector of integers of element indices % if iscell(name) diff --git a/interfaces/matlab/toolbox/@ThermoPhase/elementName.m b/interfaces/matlab/toolbox/@ThermoPhase/elementName.m index 8468c5877..b207f45b9 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/elementName.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/elementName.m @@ -1,10 +1,16 @@ function nm = elementName(tp, m) -% ELEMENTNAME - Name of element with index m. -% -% If m is a scalar integer, the return value will be a string -% containing the name of the m^th species. If it is an array of -% integers, the output will be a cell array of -% the same shape containing the name strings. +% ELEMENTNAME Get the name of an element given its index. +% nm = elementName(tp, m) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :param m: +% Scalar or vector of integers of element indices +% :return: +% If m is a scalar integer, the return value will be a string +% containing the name of the m^th species. If it is an array of +% integers, the output will be a cell array of +% the same shape containing the name strings. % [mm, nn] = size(m); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/enthalpies_RT.m b/interfaces/matlab/toolbox/@ThermoPhase/enthalpies_RT.m index 01d96e1c1..694779072 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/enthalpies_RT.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/enthalpies_RT.m @@ -1,13 +1,14 @@ function v = enthalpies_RT(tp) -% ENTHALPIES_RT - Pure species non-dimensional enthalpies. -% -% h_rt = enthalpies_RT(phase) -% -% sets array h_rt to the array of standard-state species enthalpies -% for phase 'phase' divided by RT, where R is the universal gas -% constant and T is the temperature. For gaseous species, these -% values are ideal gas enthalpies. -% +% ENTHALPIES_RT Get the non-dimensional enthalpies. +% v = enthalpies_RT(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of sensible species enthalpies +% divided by RT, where R is the universal gas +% constant and T is the temperature. For gaseous species, these +% values are ideal gas enthalpies. % v = thermo_get(tp.tp_id, 32); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/enthalpy_mass.m b/interfaces/matlab/toolbox/@ThermoPhase/enthalpy_mass.m index 774acfdac..aa7cc2fd7 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/enthalpy_mass.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/enthalpy_mass.m @@ -1,5 +1,11 @@ function v = enthalpy_mass(tp) -% ENTHALPY_MASS - Specific enthalpy [J/kg]. +% ENTHALPY_MASS Get the mass specific enthalpy. +% v = enthalpy_mass(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of mass specific enthalpies of the species. Units: J/kg % v = thermo_get(tp.tp_id, 9); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/enthalpy_mole.m b/interfaces/matlab/toolbox/@ThermoPhase/enthalpy_mole.m index 4db2d8013..f87bd1ddd 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/enthalpy_mole.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/enthalpy_mole.m @@ -1,5 +1,11 @@ function v = enthalpy_mole(a) -% ENTHALPY_MOLE - Molar enthalpy [J/kmol]. +% ENTHALPY_MOLE Get the mole specific enthalpy. +% v = enthalpy_mole(a) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of molar specific enthalpies of the species. Units: J/kmol % v = thermo_get(a.tp_id, 2); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/entropies_R.m b/interfaces/matlab/toolbox/@ThermoPhase/entropies_R.m index 653299c0c..7207f4934 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/entropies_R.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/entropies_R.m @@ -1,8 +1,11 @@ function s = entropies_R(tp) -% ENTROPIES_R - Species non-dimensional entropies. -% -% This method returns an array containing the pure species -% standard-state entropies. +% ENTROPIES_R Get the non-dimensional entropy. +% s = entropies_R(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of species non-dimensional entropies. % s = thermo_get(tp.tp_id, 36); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/entropy_mass.m b/interfaces/matlab/toolbox/@ThermoPhase/entropy_mass.m index eb6c7a8ea..f9b02ad2b 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/entropy_mass.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/entropy_mass.m @@ -1,3 +1,11 @@ function v = entropy_mass(tp) +% ENTROPY_MASS Get the mass specific entropy. +% v = entropy_mass(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of mass specific entropies of the species. Units: J/kg-K +% v = thermo_get(tp.tp_id, 11); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/entropy_mole.m b/interfaces/matlab/toolbox/@ThermoPhase/entropy_mole.m index e5b5de893..7b1bbf127 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/entropy_mole.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/entropy_mole.m @@ -1,3 +1,11 @@ function v = entropy_mole(tp) +% ENTROPY_MOLE Get the mole specific entropy. +% v = entropy_mole(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of molar specific entropies of the species. Units: J/kg +% v = thermo_get(tp.tp_id, 4); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/eosType.m b/interfaces/matlab/toolbox/@ThermoPhase/eosType.m index 18d820f04..3a9e88c8d 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/eosType.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/eosType.m @@ -1,8 +1,12 @@ function e = eosType(tp) -% EOSTYPE - Equation of state type. -% -% This method returns an integer flag identifying the type of -% equation of state. +% EOSTYPE Get the type of the equation of state. +% e = eosType(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% An integer flag identifying the type of equation of state. +% See the definitions in include/cantera/thermo/mix_defs.h % e = thermo_get(tp.tp_id, 18); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/equilibrate.m b/interfaces/matlab/toolbox/@ThermoPhase/equilibrate.m index 170b1ae3e..2b94c88aa 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/equilibrate.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/equilibrate.m @@ -1,29 +1,32 @@ function tp = equilibrate(tp, xy, solver, rtol, maxsteps, maxiter, loglevel) % EQUILIBRATE Set the phase to a state of chemical equilibrium. -% -% XY -- A two-letter string, which must be one of the set -% ['TP','TV','HP','SP','SV','UV','PT','VT','PH','PS','VS','VU']. -% If H, U, S, or V is specified, the value must be the specific -% value (per unit mass). -% -% solver -- specifies the equilibrium solver to use. If solver -% = 0, a fast solver using the element potential method will be -% used. If solver > 0, a slower but more robust Gibbs -% minimization solver will be used. If solver < 0 or is -% unspecified, the fast solver will be tried first, then if it -% fails the other will be tried. -% -% rtol -- the relative error tolerance. -% -% maxsteps -- maximum number of steps in composition to take to -% find a converged solution. -% -% maxiter -- for the Gibbs minimization solver only, this -% specifies the number of 'outer' iterations on T or P when -% some property pair other than TP is specified. -% -% loglevel -- set to a value > 0 to write diagnostic output -% Larger values generate more detailed information. +% tp = equilibrate(tp, xy, solver, rtol, maxsteps, maxiter, loglevel) +% :param XY: +% A two-letter string, which must be one of the set +% ``['TP','TV','HP','SP','SV','UV','UP']``, +% indicating which pair of properties should be held constant. +% Not all of the properties to be held constant are available with +% all of the solvers. +% :param solver: +% Specifies the equilibrium solver to use. If solver = 0, a fast +% solver using the element potential method will be used. If +% solver = 1, a slower but more robust Gibbs minimization solver +% will be used. If solver >= 2, a version of the VCS algorithm will +% be used. If solver < 0 or is unspecified, the fast solver +% will be tried first, then if it fails the Gibbs minimization solver +% will be tried. +% :param rtol: +% The relative error tolerance. +% :param maxsteps: +% Maximum number of steps in composition to take to find a +% converged solution. +% :param maxiter: +% For the Gibbs minimization solver only, this specifies the number +% of 'outer' iterations on T or P when some property pair other than +% TP is specified. +% :param loglevel: +% Set to a value > 0 to write diagnostic output. Larger values +% generate more detailed information. % % use the ChemEquil solver by default diff --git a/interfaces/matlab/toolbox/@ThermoPhase/gibbs_RT.m b/interfaces/matlab/toolbox/@ThermoPhase/gibbs_RT.m index fbdc3e9d2..46685eb32 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/gibbs_RT.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/gibbs_RT.m @@ -1,8 +1,11 @@ function g_RT = gibbs_RT(tp) -% GIBBS_RT - Species non-dimensional Gibbs free energies. -% -% This method returns an array containing the pure species -% standard-state Gibbs free energies. +% GIBBS_RT Get the non-dimensional Gibbs function. +% g_RT = gibbs_RT(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of non-dimensional Gibbs functions of the species. % g_RT = enthalpies_RT(tp) - entropies_R(tp); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/gibbs_mass.m b/interfaces/matlab/toolbox/@ThermoPhase/gibbs_mass.m index b2868f77c..e1173e0cb 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/gibbs_mass.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/gibbs_mass.m @@ -1,4 +1,12 @@ function v = gibbs_mass(tp) -% GIBBS_MASS - Specific Gibbs function [J/kg]. +% GIBBS_MASS Get the mass specific Gibbs function. +% v = gibbs_mass(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of mass specific Gibbs functions of the species. +% Units: J/kg +% v = thermo_get(tp.tp_id, 12); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/gibbs_mole.m b/interfaces/matlab/toolbox/@ThermoPhase/gibbs_mole.m index 32b4823ce..66c37c4c9 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/gibbs_mole.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/gibbs_mole.m @@ -1,4 +1,12 @@ function v = gibbs_mole(tp) -% GIBBS_MOLE - Molar Gibbs function [J/kmol]. +% GIBBS_MOLE Get the mole specific Gibbs function. +% v = gibbs_mole(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of mole specific Gibbs functions of the species. +% Units: J/kmol +% v = thermo_get(tp.tp_id, 5); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/hndl.m b/interfaces/matlab/toolbox/@ThermoPhase/hndl.m index 760c55198..1e210b920 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/hndl.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/hndl.m @@ -1,4 +1,8 @@ function i = hndl(p) +% HNDL Get the integer used to access the kernel object. +% i = hndl(p) +% Deprecated in favor of :mat:func:`thermo_hndl`. +% warning('This function is deprecated in favor of thermo_hndl.m') i = p.tp_id; diff --git a/interfaces/matlab/toolbox/@ThermoPhase/intEnergy_mass.m b/interfaces/matlab/toolbox/@ThermoPhase/intEnergy_mass.m index 450a34625..476ab5c09 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/intEnergy_mass.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/intEnergy_mass.m @@ -1,4 +1,12 @@ function v = intEnergy_mass(tp) -% INTENERGY_MASS - Specific internal energy [J/kg]. +% INTENERGY_MASS Get the mass specific internal energy. +% v = intEnergy_mass(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of mass specific internal energies of the species. +% Units: J/kg +% v = thermo_get(tp.tp_id, 10); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/intEnergy_mole.m b/interfaces/matlab/toolbox/@ThermoPhase/intEnergy_mole.m index fa0bb33b2..ee0a8b214 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/intEnergy_mole.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/intEnergy_mole.m @@ -1,3 +1,12 @@ function v = intEnergy_mole(tp) -% INTENERGY_MOLE - Molar internal energy [J/kmol]. +% INTENERGY_MOLE Get the mole specific internal energy. +% v = intEnergy_mole(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of mole specific internal energies of the species. +% Units: J/kmol +% + v = thermo_get(tp.tp_id, 3); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/isIdealGas.m b/interfaces/matlab/toolbox/@ThermoPhase/isIdealGas.m index e72b396c7..fee1bb2bc 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/isIdealGas.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/isIdealGas.m @@ -1,6 +1,12 @@ function v = isIdealGas(tp) -% ISIDEALGAS - True if the phase is an ideal gas or ideal gas -% mixture, and false otherwise. +% ISIDEALGAS Get a flag indicating whether the phase is an ideal gas. +% v = isIdealGas(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% True (1) if the phase is an ideal gas or ideal gas +% mixture, and false (0) otherwise. % if eosType(tp) == 1 diff --git a/interfaces/matlab/toolbox/@ThermoPhase/isothermalCompressibility.m b/interfaces/matlab/toolbox/@ThermoPhase/isothermalCompressibility.m index a0e57386c..467c80742 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/isothermalCompressibility.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/isothermalCompressibility.m @@ -1,9 +1,11 @@ function b = isothermalCompressibility(tp) -% ISOTHERMALCOMPRESSIBILITY - Isothermal Compressibility [1/Pa] -% -% b = isothermalCompressibility(a) -% Return the isothermal compressibility of ThermoPhase a -% in units of 1/Pa +% ISOTHERMALCOMPRESSIBILITY Get the isothermal compressibility. +% b = isothermalCompressibility(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Isothermal Compressibility. Units: 1/Pa % b = thermo_get(tp.tp_id, 26); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/massFraction.m b/interfaces/matlab/toolbox/@ThermoPhase/massFraction.m index 0c2ca935a..82fd33dea 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/massFraction.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/massFraction.m @@ -1,4 +1,15 @@ function y = massFraction(tp, species) +% MASSFRACTION Get the mass fraction of a species. +% y = massFraction(tp, species) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :param species: +% String or cell array of strings of species whose mass +% fraction is desired +% :return: +% Scalar or vector double mass fractions +% y = 0.0; yarray = massFractions(tp); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/massFractions.m b/interfaces/matlab/toolbox/@ThermoPhase/massFractions.m index da191ce5c..d76c564ae 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/massFractions.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/massFractions.m @@ -1,10 +1,12 @@ function y = massFractions(tp) -% MASSFRACTIONS - Mass fractions. -% -% massFractions(phase); -% -% returns the array of species mass fractions for phase 'phase'. If -% no output argument is specified, a bar plot is produced. +% MASSFRACTIONS Get the mass fractions of all species. +% y = massFractions(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of species mass fractions for input phase. If +% no output argument is specified, a bar plot is produced. % y = phase_get(tp.tp_id, 21); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/maxTemp.m b/interfaces/matlab/toolbox/@ThermoPhase/maxTemp.m index e5e97c748..3e0ccb092 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/maxTemp.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/maxTemp.m @@ -1,13 +1,18 @@ function v = maxTemp(tp) -% MAXTEMP - Maximum temperature. +% MAXTEMP Get the maximum temperature of the parameter fits. +% v = maxTemp(tp) +% The parameterizations used to represent the temperature-dependent +% species thermodynamic properties are generally only valid in some +% finite temperature range, which may be different for each species +% in the phase. % -% The parameterizations used to represent the temperature-dependent -% species thermodynamic properties are generally only valid in some -% finite temperature range, which may be different for each species -% in the phase. This method returns the highest temperature at which -% the parameterizations are valid for all species in the phase. +% See also: :mat:func:`minTemp` % -% See also: minTemp +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of maximum temperatures of all species % v = thermo_get(tp.tp_id, 17); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/meanMolarMass.m b/interfaces/matlab/toolbox/@ThermoPhase/meanMolarMass.m index c6489fa0a..cc078fa5c 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/meanMolarMass.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/meanMolarMass.m @@ -1,8 +1,9 @@ function mmm = meanMolarMass(tp) -% MEANMOLARMASS - Mean molar mass [kg/kmol]. +% MEANMOLARMASS Get the mean molecular weight. +% wtm = meanMolarMass(tp) +% Deprecated in favor of :mat:func:`meanMolecularWeight` % -% The mean molar mass is the mole-fraction-weighted sum of the -% molar masses of the individual species in the phase. +% See also: :mat:func:`meanMolecularWeight` % warning('Deprecated in favor of meanMolecularWeight.m') diff --git a/interfaces/matlab/toolbox/@ThermoPhase/meanMolecularWeight.m b/interfaces/matlab/toolbox/@ThermoPhase/meanMolecularWeight.m index c26053ed6..84a3e2cdb 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/meanMolecularWeight.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/meanMolecularWeight.m @@ -1,10 +1,14 @@ function mmw = meanMolecularWeight(tp) -% MEANMOLECULARWEIGHT - Mean molecular weight. +% MEANMOLECULARWEIGHT Get the mean molecular weight. +% wtm = meanMolecularWeight(tp) +% The mean molecular weight is the mole-fraction-weighted sum of the +% molar masses of the individual species in the phase. % -% This method is a synonym for method meanMolarMass and is -% provided for backward compatibility. -% -% See also; meanMolarMass +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Scalar double mean molecular weight. Units: kg/kmol % mmw = phase_get(tp.tp_id,4); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/minTemp.m b/interfaces/matlab/toolbox/@ThermoPhase/minTemp.m index 4dd30702e..56c69e25d 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/minTemp.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/minTemp.m @@ -1,13 +1,18 @@ function v = minTemp(tp) -% MINTEMP - Minimum temperature. +% MINTEMP Get the minimum temperature of the parameter fits. +% v = minTemp(tp) +% The parameterizations used to represent the temperature-dependent +% species thermodynamic properties are generally only valid in some +% finite temperature range, which may be different for each species +% in the phase. % -% The parameterizations used to represent the temperature-dependent -% species thermodynamic properties are generally only valid in some -% finite temperature range, which may be different for each species -% in the phase. This method returns the lowest temperature at which -% the parameterizations are valid for all species in the phase. +% See also: :mat:func:`maxTemp` % -% See also: maxTemp +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of minimum temperatures of all species % v = thermo_get(tp.tp_id, 16); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/molarDensity.m b/interfaces/matlab/toolbox/@ThermoPhase/molarDensity.m index 864cd3966..eee8c462e 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/molarDensity.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/molarDensity.m @@ -1,5 +1,11 @@ function n = molarDensity(tp) -% MOLARDENSITY - Molar density [kmol/m^3]. +% MOLARDENSITY Get the molar density. +% n = molarDensity(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Molar density. Units: kmol/m^3 % n = phase_get(tp.tp_id, 3); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/molarMasses.m b/interfaces/matlab/toolbox/@ThermoPhase/molarMasses.m index fc051e9a2..2084c430e 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/molarMasses.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/molarMasses.m @@ -1,5 +1,9 @@ function mm = molarMasses(tp) -% MOLARMASSES - Array of species molar masses [kg/kmol]. +% MOLARMASSES Get the molecular weights of all the species. +% x = molarMasses(a) +% Deprecated in favor of :mat:func:`molecularWeights` +% +% See also: :mat:func:`molecularWeights` % warning('Deprecated in favor of molecularWeights.m') diff --git a/interfaces/matlab/toolbox/@ThermoPhase/moleFraction.m b/interfaces/matlab/toolbox/@ThermoPhase/moleFraction.m index fea5d2228..1adaaa5a8 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/moleFraction.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/moleFraction.m @@ -1,4 +1,15 @@ function x = moleFraction(tp, species) +% MOLEFRACTION Get the mole fraction of a species. +% x = moleFraction(tp, species) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :param species: +% String or cell array of strings of species whose mole +% fraction is desired +% :return: +% Scalar or vector double mole fractions +% x = 0.0; xarray = moleFractions(tp); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/moleFractions.m b/interfaces/matlab/toolbox/@ThermoPhase/moleFractions.m index c49a8a338..2d1a4ba7f 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/moleFractions.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/moleFractions.m @@ -1,10 +1,12 @@ function x = moleFractions(tp) -% MOLEFRACTIONS - Mole fractions. -% -% moleFractions(phase) -% -% returns the array of species mole fractions for phase 'phase'. If -% no output argument is specified, a bar plot is produced. +% MOLEFRACTIONS Get the mole fractions of all species. +% x = moleFractions(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of species mole fractions for input phase. If +% no output argument is specified, a bar plot is produced. % x = phase_get(tp.tp_id, 20); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/molecularWeights.m b/interfaces/matlab/toolbox/@ThermoPhase/molecularWeights.m index 96201172b..49a2e6e06 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/molecularWeights.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/molecularWeights.m @@ -1,9 +1,12 @@ function mw = molecularWeights(tp) -% MOLECULARWEIGHTS - Array of species molar masses [kg/kmol]. +% MOLECULARWEIGHTS Get the molecular weights of the species. +% x = molecularWeights(tp) % -% This method is deprecated - use molarMasses instead. -% -% See also: molarMasses +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Vector of species molecular weights. Units: kg/kmol % mw = phase_get(tp.tp_id, 22); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/nAtoms.m b/interfaces/matlab/toolbox/@ThermoPhase/nAtoms.m index 75947cb1f..6ef1b2bc5 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/nAtoms.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/nAtoms.m @@ -1,5 +1,16 @@ -function n = nAtoms(tp, k, m) -% NATOMS - Number of atoms of element m in species k. +function n = nAtoms(tp,k,m) +% NATOMS Get the number of atoms of an element in a species. +% n = nAtoms(tp,k,m) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :param k: +% String species name or integer species number +% :param m: +% String element name or integer element number +% :return: +% Number of atoms of element ``m`` in species ``k``. +% if nargin == 3 if ischar(m) diff --git a/interfaces/matlab/toolbox/@ThermoPhase/nElements.m b/interfaces/matlab/toolbox/@ThermoPhase/nElements.m index a93c679f8..949f3b5bb 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/nElements.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/nElements.m @@ -1,5 +1,11 @@ function n = nElements(tp) -% NELEMENTS - Number of elements in the phase. +% NELEMENTS Get the number of elements. +% n = nElements(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Number of elements in the phase. % n = phase_get(tp.tp_id, 10); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/nSpecies.m b/interfaces/matlab/toolbox/@ThermoPhase/nSpecies.m index c45f9c9f6..1ba41e1aa 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/nSpecies.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/nSpecies.m @@ -1,5 +1,11 @@ function n = nSpecies(tp) -% NSPECIES - Number of species in the phase. +% NSPECIES Get the number of species. +% n = nSpecies(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Number of species in the phase. % n = phase_get(tp.tp_id, 11); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/name.m b/interfaces/matlab/toolbox/@ThermoPhase/name.m index 772bac16d..297d168f7 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/name.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/name.m @@ -1,4 +1,11 @@ function nm = name(tp) -% NAME - user-specified phase name. +% NAME Get the name of the phase. +% nm = name(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% String name of the input phase +% nm = phase_get(thermo_hndl(tp), 42); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/ph.m b/interfaces/matlab/toolbox/@ThermoPhase/ph.m index fc9c4ad31..53fb0f8b0 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/ph.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/ph.m @@ -1,4 +1,11 @@ function i = ph(tp) -disp('method ph is deprecated.'); +% PH Get the ph field of the phase. +% i = ph(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% +warning('method ph is deprecated.'); i = tp.ph; diff --git a/interfaces/matlab/toolbox/@ThermoPhase/pressure.m b/interfaces/matlab/toolbox/@ThermoPhase/pressure.m index 85e846431..bdf727979 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/pressure.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/pressure.m @@ -1,5 +1,11 @@ function v = pressure(tp) -% PRESSURE - Pressure [Pa]. +% PRESSURE Get the pressure. +% v = pressure(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Pressure. Units: Pa % v = thermo_get(tp.tp_id, 8); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/refPressure.m b/interfaces/matlab/toolbox/@ThermoPhase/refPressure.m index 302c20376..ff8cb3bc5 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/refPressure.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/refPressure.m @@ -1,7 +1,12 @@ function v = refPressure(tp) -% REFPRESSURE - Reference pressure [Pa]. -% -% All standard-state thermodynamic properties are for this pressure. +% REFPRESSURE Get the reference pressure. +% v = refPressure(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :return: +% Reference pressure in Pa. All standard-state +% thermodynamic properties are for this pressure. % v = thermo_get(tp.tp_id, 15); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/satPressure.m b/interfaces/matlab/toolbox/@ThermoPhase/satPressure.m index d0b859bd5..55a2f1936 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/satPressure.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/satPressure.m @@ -1,4 +1,13 @@ function v = satPressure(tp, T) -% SATPRESSURE - Saturation pressure for temperature T. +% SATPRESSURE Get the saturation pressure for a given temperature. +% v = satPressure(tp, T) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :param T: +% Temperature Units: K +% :return: +% Saturation pressure for temperature T. Units: Pa +% v = thermo_get(tp.tp_id, 24, T); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/satTemperature.m b/interfaces/matlab/toolbox/@ThermoPhase/satTemperature.m index 48f02afa8..d8fdc897c 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/satTemperature.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/satTemperature.m @@ -1,4 +1,13 @@ function v = satTemperature(tp, p) -% SATTEMPERATURE - Saturation temperature for pressure p. +% SATTEMPERATURE Get the saturation temperature for a given pressure. +% v = satTemperature(tp, p) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :param p: +% Pressure. Units: Pa +% :return: +% Saturation temperature for pressure p. Units: K +% v = thermo_get(tp.tp_id, 23, p); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/set.m b/interfaces/matlab/toolbox/@ThermoPhase/set.m index 8692f851b..87dda9580 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/set.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/set.m @@ -1,39 +1,52 @@ function set(tp, varargin) -% SET - Set properties. +% SET Set properties of a phase. +% set(tp,varargin) +% The properties that may be set are % -% The properties that may be set are +% * Temperature (T) +% * Density (Rho) +% * Volume (V) +% * Pressure (P) +% * Enthalpy (H) +% * Entropy (S) +% * Mole Fractions (X) +% * Mass Fractions (Y) +% * Vapor Fraction (Vapor) +% * Liquid Fraction (Liquid) % -% Temperature (T) -% Density (Rho) -% Volume (V) -% Pressure (P) -% Enthalpy (H) -% Entropy (S) -% MoleFractions (X) -% MassFractions (Y) -% Vapor Fraction (Vapor) -% Liquid Fractio (Liquid) +% Either the full property name or the symbol may be +% specified. For the extensive properties (V,H,U,S), the values +% must be given per unit mass. H, U, and S must be set in +% conjunction with pressure (for H,S) or volume (for U,S). Either +% (specific) volume or density may be specified. Mole and mass +% fractions must be input as vectors (either row or column) with +% length equal to the number of species. Two properties may be +% specified in a single call to :mat:func:`set`, plus one of +% mass fractions or mole fractions. % -% Either the full property name or the symbol may be -% specified. For the extensive properties (V,H,U,S), the values -% must be given per unit mass. H, U, and S must be set in -% conjunction with pressure (for H,S) or volume (for U,S). Either -% (specific) volume or density may be specified. Mole and mass -% fractions must be input as vectors (either row or column) with -% length equal to the number of species. +% Examples:: % -% Examples: +% >> set(gas,'Temperature',600.0); +% >> set(gas,'T',600.0); +% >> set(gas,'T',600.0,'P',2*oneatm,'Y',massfracs); +% >> set(gas,'H',0.5*enthalpy_mass(gas),'P',pressure(gas)); +% >> set(gas,'S',entropy_mass(gas),'P',0.5*pressure(gas)); +% >> set(gas,'X',ones(nSpecies(gas),1)); +% >> set(gas,'T',500.0,'Vapor',0.8) % -% set(gas,'Temperature',600.0); -% set(gas,'T',600.0); -% set(gas,'T',600.0,'P',2*oneatm,'Y',massfracs); -% set(gas,'H',0.5*enthalpy_mass(gas),'P',pressure(gas)); -% set(gas,'S',entropy_mass(gas),'P',0.5*pressure(gas)); -% set(gas,'X',ones(nSpecies(gas),1)); -% set(gas,'T',500.0,'Vapor',0.8) +% Alternatively, individual methods to set properties may be +% called (setTemperature, setMoleFractions, etc.) % -% Alternatively, individual methods to set properties may be -% called (setTemperature, setMoleFractions, etc.) +% See also: :mat:func:`setDensity`, :mat:func:`setMassFractions`, +% :mat:func:`setMoleFractions`, :mat:func:`setPressure`, :mat:func:`setState_HP`, +% :mat:func:`setState_Psat`, :mat:func:`setState_SP`, :mat:func:`setState_SV`, +% :mat:func:`setState_Tsat`, :mat:func:`setState_UV`, :mat:func:`setTemperature` +% +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object that derives from ThermoPhase) +% :param varargin: +% Comma separated list of ``property, value`` pairs to be set % property_argin = varargin; diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setDensity.m b/interfaces/matlab/toolbox/@ThermoPhase/setDensity.m index 18fd8978b..53834c6e7 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setDensity.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setDensity.m @@ -1,7 +1,11 @@ function setDensity(tp, rho) -% SETDENSITY - Set the density [kg/m^3]. -% -% setDensity(phase, 0.01); +% SETDENSITY Set the density. +% setDensity(tp,rho) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param rho: +% Density. Units: kg/m**3 % if rho <= 0.0 diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setElectricPotential.m b/interfaces/matlab/toolbox/@ThermoPhase/setElectricPotential.m index 67efd77f8..f0e8a202b 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setElectricPotential.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setElectricPotential.m @@ -1,5 +1,11 @@ -function setElectricPotential(tp, phi) -% SETELECTRICPOTENTIAL Set the electric potential [V]. +function setElectricPotential(tp,phi) +% SETELECTRICPOTENTIAL Set the electric potential. +% setElectricPotential(tp,phi) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param phi: +% Electric potential. Units: V % thermo_set(tp.tp_id, 2, phi); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setMassFractions.m b/interfaces/matlab/toolbox/@ThermoPhase/setMassFractions.m index 8efaebc98..ee08b9e29 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setMassFractions.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setMassFractions.m @@ -1,34 +1,30 @@ function setMassFractions(tp, y, norm) % SETMASSFRACTIONS Set the species mass fractions. +% setMassFractions(tp, y, norm) +% Note that calling :mat:func:`setMassFractions` leaves the temperature and +% density unchanged, and therefore the pressure changes if the new +% composition has a molar mass that is different than the old +% composition. If it is desired to change the composition and hold +% the pressure fixed, use method :mat:func:`set` and specify the mass +% fractions and the pressure, or call :mat:func:`setPressure` +% after calling :mat:func:`setMassFractions`. % -% setMassFractions(a,y) -% -% If y is a vector of doubles, this call sets the species mass -% fractions to the values in y and then scales them so that they -% sum to 1.0. The length of y must equal the number of species. -% -% If y is a string, then the mass fractions of the listed -% species are set to the specified values, and all others are -% set to zero. The syntax for the string is as shown in these -% examples: -% 'CH4:4, O2:2, AR:3' -% 'SIH2:0.9,H2:0.1' -% -% setMassFractions(a, y, 'nonorm') -% -% As above, but the normalization step is skipped. This only -% works if y is an array, not a string. Since unnormalized mass -% fractions can lead to unphysical results, 'nonorm' should be -% used only in rare cases, such as computing partial -% derivatives with respect to a species mass fraction. -% -% Note that calling setMassFractions leaves the temperature and -% density unchanged, and therefore the pressure changes if the new -% composition has a molar mass that is different than the old -% composition. If it is desired to change the composition and hold -% the pressure fixed, use method 'set' (defined in class Solution) -% instead, or call setPressure after calling setMassFractions. +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param y: +% Vector of mass fractions whose length must be the same as +% the number of species. Alternatively, a string in the format +% ``'SPEC:Y,SPEC2:Y2'`` that specifies the mass fraction of +% specific species. +% :param norm: +% If ``'nonorm'`` is specified, ``y`` will be normalized. This only +% works if ``y`` is a vector, not a string. Since unnormalized mass +% fractions can lead to unphysical results, ``'nonorm'`` should be +% used only in rare cases, such as computing partial +% derivatives with respect to a species mass fraction. % + if isa(y, 'double') if nargin == 3 if strcmp(norm, 'nonorm') diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setMoleFractions.m b/interfaces/matlab/toolbox/@ThermoPhase/setMoleFractions.m index 90c4d3a47..8a1a4c4dc 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setMoleFractions.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setMoleFractions.m @@ -1,33 +1,29 @@ function setMoleFractions(tp, x, norm) % SETMOLEFRACTIONS Set the species mole fractions. +% setMoleFractions(tp,x,norm) +% Note that calling :mat:func:`setMoleFractions` leaves the temperature and +% density unchanged, and therefore the pressure changes if the new +% composition has a molar mass that is different than the old +% composition. If it is desired to change the composition and hold +% the pressure fixed, use method :mat:func:`set` and specify the mole +% fractions and the pressure, or call :mat:func:`setPressure` +% after calling :mat:func:`setmoleFractions`. % -% setMoleFractions(a,x) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param y: +% Vector of mole fractions whose length must be the same as +% the number of species. Alternatively, a string in the format +% ``'SPEC:Y,SPEC2:Y2'`` that specifies the mole fraction of +% specific species. +% :param norm: +% If ``'nonorm'`` is specified, ``y`` will be normalized. This only +% works if ``y`` is a vector, not a string. Since unnormalized mole +% fractions can lead to unphysical results, ``'nonorm'`` should be +% used only in rare cases, such as computing partial +% derivatives with respect to a species mole fraction. % -% If x is a vector of doubles, this call sets the species mole -% fractions to the values in x and then scales them so that they -% sum to 1.0. The length of x must equal the number of species. -% -% If x is a string, then the mole fractions of the listed -% species are set to the specified values, and all others are -% set to zero. The syntax for the string is as shown in these -% examples: -% 'CH4:4, O2:2, AR:3' -% 'SIH2:0.9,H2:0.1' -% -% setMoleFractions(a, x, 'nonorm') -% -% As above, but the normalization step is skipped. This only -% works if x is an array, not a string. Since unnormalized mole -% fractions can lead to unphysical results, 'nonorm' should be -% used only in rare cases, such as computing partial -% derivatives with respect to a species mole fraction. -% -% Note that calling setMoleFractions leaves the temperature and -% density unchanged, and therefore the pressure changes if the new -% composition has a molar mass that is different than the old -% composition. If it is desired to change the composition and hold -% the pressure fixed, use method 'set' (defined in class Solution) -% instead, or call setPressure after calling setMoleFractions. if isa(x, 'double') if nargin == 3 diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setName.m b/interfaces/matlab/toolbox/@ThermoPhase/setName.m index bc96767e7..b0987c282 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setName.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setName.m @@ -1,5 +1,11 @@ function setName(tp, name) -% SETNAME - Set the name of the phase. +% SETNAME Set the name of the phase. +% setName(tp, name) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param name: +% String, name of the phase % if isa(name,'char') diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setPressure.m b/interfaces/matlab/toolbox/@ThermoPhase/setPressure.m index 7e8e18eed..16cea3959 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setPressure.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setPressure.m @@ -1,8 +1,14 @@ function setPressure(tp, p) -% SETPRESSURE Set the pressure [Pa]. +% SETPRESSURE Set the pressure. +% setPressure(tp,p) +% The pressure is set by changing the density holding the +% temperature and chemical composition fixed. % -% The pressure is set by changing the density holding the -% temperature and chemical composition fixed. +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param p: +% Pressure. Units: Pa % if p <= 0.0 diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState.m b/interfaces/matlab/toolbox/@ThermoPhase/setState.m index e94a90f68..b99f96b8e 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState.m @@ -1,5 +1,12 @@ function setState(a, job, values) -disp('deprecated') +% SETSTATE Set the state. +% a = setState(a,job,values) +% Deprecated in favor of :mat:func:`set` +% +% See also: :mat:func:`set` +% + +warning('deprecated in favor of set.m') if nargin ~= 3 || ~isa(job, 'char') error('Syntax error. Type "help setState" for more information.') end diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState_HP.m b/interfaces/matlab/toolbox/@ThermoPhase/setState_HP.m index e7cb497c0..8419350b4 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState_HP.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState_HP.m @@ -1,10 +1,12 @@ function setState_HP(tp, hp) -% SETSTATE_HP - Set the specific enthalpy [J/kg] and pressure [Pa]. -% -% setState_HP(a, hp) sets the specific enthalpy and pressure -% of object a, holding its composition fixed. Argument 'hp' must -% be a vector of length 2 containing the desired values for the specific -% enthalpy (J/kg) and pressure (Pa). +% SETSTATE_HP Set the specific enthalpy and pressure. +% setState_HP(tp,hp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param hp: +% Vector of length 2 containing the desired values for the specific +% enthalpy (J/kg) and pressure (Pa). % if hp(2) <= 0.0 diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState_Psat.m b/interfaces/matlab/toolbox/@ThermoPhase/setState_Psat.m index 2a457dd89..1d4a5e256 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState_Psat.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState_Psat.m @@ -1,5 +1,10 @@ function setState_Psat(tp, px) -% SETSTATE_PSAT Set the fluid to a saturated state at -% pressure P +% SETSTATE_PSAT Set the fluid to a saturated state at a given pressure. +% setState_Psat(tp,px) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param px: +% Pressure. Units: Pa % thermo_set(tp.tp_id, 24, px); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState_SP.m b/interfaces/matlab/toolbox/@ThermoPhase/setState_SP.m index 415c46592..621ffe2aa 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState_SP.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState_SP.m @@ -1,10 +1,12 @@ function setState_SP(tp, sp) -% SETSTATE_SP Set the specific entropy [J/kg/K] and pressure [Pa]. -% -% setState_SP(a, sp) sets the specific entropy and pressure -% of object a, holding its composition fixed. Argument 'sp' must -% be a vector of length 2 containing the desired values for the specific -% entropy (J/kg/K) and pressure (Pa). +% SETSTATE_SP Set the specific entropy and pressure. +% setState_SP(tp,sp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param sp: +% Vector of length 2 containing the desired values for the specific +% entropy (J/kg-K) and pressure (Pa). % if sp(1) <= 0.0 diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState_SV.m b/interfaces/matlab/toolbox/@ThermoPhase/setState_SV.m index f44ea1095..9ef51acbe 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState_SV.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState_SV.m @@ -1,11 +1,12 @@ function setState_SV(tp, sv) -% SETSTATE_SV Set the specific entropy [J/kg/K] and specific -% volume [m3/kg]. -% -% setState_SV(a, sv) sets the specific entropy and specific volume -% of object a, holding its composition fixed. Argument 'sv' must -% be a vector of length 2 containing the desired values for the specific -% entropy (J/kg/K) and specific volume (m3/kg). +% SETSTATE_SV Set the specific entropy and specific volume. +% setState_SV(tp,sv) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param sv: +% Vector of length 2 containing the desired values for the specific +% entropy (J/kg-K) and specific volume (m**3/kg). % if sv(1) <= 0.0 diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState_Tsat.m b/interfaces/matlab/toolbox/@ThermoPhase/setState_Tsat.m index 79e0a2733..765f4959d 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState_Tsat.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState_Tsat.m @@ -1,6 +1,11 @@ function setState_Tsat(tp, tx) -% SETSTATE_TSAT Set the fluid to a saturated state at -% temperature t +% SETSTATE_TSAT Set the fluid to a saturated state at a given temperature. +% setState_Tsat(tp,tx) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param tx: +% Temperature. Units: K % thermo_set(tp.tp_id, 25, tx); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState_UV.m b/interfaces/matlab/toolbox/@ThermoPhase/setState_UV.m index ebfb656ef..c1f3e7874 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState_UV.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState_UV.m @@ -1,12 +1,13 @@ function setState_UV(tp, uv) -% SETSTATE_UV Set the specific internal energy [J/kg] and -% specific volume [m^3/kg]. -% -% setState_UV(a, uv) sets the specific internal energy and -% specific volume of object a, holding its composition -% fixed. Argument 'uv' must be a vector of length 2 containing -% the desired values for the specific internal energy (J/kg) and -% specific volume (m^3/kg). +% SETSTATE_UV Set the specific internal energy and specific volume. +% setState_UV(tp,uv) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param uv: +% Vector of length 2 containing +% the desired values for the specific internal energy (J/kg) and +% specific volume (m**3/kg). % if uv(2) <= 0.0 diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState_satLiquid.m b/interfaces/matlab/toolbox/@ThermoPhase/setState_satLiquid.m index ed594d5b4..5afb29c91 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState_satLiquid.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState_satLiquid.m @@ -1,6 +1,9 @@ function setState_satLiquid(tp) -% SETSTATE_SATLIQUID Set the fluid to the saturated liquid state -% at the current temperature. +% SETSTATE_SATLIQUID Set the fluid to the saturated liquid state at the current temperature. +% setState_satLiquid(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) % thermo_set(tp.tp_id, 2, 0); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setState_satVapor.m b/interfaces/matlab/toolbox/@ThermoPhase/setState_satVapor.m index caa1641b3..3e0bf9ad2 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setState_satVapor.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setState_satVapor.m @@ -1,6 +1,9 @@ function setState_satVapor(tp) -% SETSTATE_SATVAPOR Set the fluid to the saturated vapor state at the -% current temperature. +% SETSTATE_SATVAPOR Set the fluid to the saturated vapor state at the current temperature. +% setState_satVapor(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) % thermo_set(tp.tp_id, 3, 0); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/setTemperature.m b/interfaces/matlab/toolbox/@ThermoPhase/setTemperature.m index 3ca93a9ec..1c8da7d0c 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/setTemperature.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/setTemperature.m @@ -1,5 +1,11 @@ function setTemperature(tp,t) -% SETTEMPERATURE Set the temperature [K]. +% SETTEMPERATURE Set the temperature. +% setTemperature(tp,t) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param t: +% Temperature. Units: K % if (t <= 0) diff --git a/interfaces/matlab/toolbox/@ThermoPhase/soundspeed.m b/interfaces/matlab/toolbox/@ThermoPhase/soundspeed.m index cfd564935..084501d7a 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/soundspeed.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/soundspeed.m @@ -1,18 +1,43 @@ -function b = soundspeed(a) -% SOUNDSPEED - Speed of sound (m/s). +function c = soundspeed(tp) +% SOUNDSPEED Get the speed of sound. +% c = soundspeed(tp) +% If the phase is an ideal gas, the speed of sound +% is calculated by: +% +% .. math:: c = \sqrt{\gamma * R * T} +% +% where :math:`\gamma` is the ratio of specific heats, :math:`R` is +% the specific gas constant, and :math:`T` is the temperature. If the +% phase is not an ideal gas, the speed of sound is calculated by +% +% .. math:: c = \sqrt{\left(\frac{\partial p}{\partial \rho}\right)_s} +% +% where :math:`p` is the pressure and :math:`\rho` is the density, +% and the subscript :math:`s` indicates constant entropy. This is +% approximated by slightly increasing the density at constant entropy +% and computing the change in pressure. +% +% .. math:: c = \sqrt{\frac{p_1 - p_0}{\rho_1-\rho_0}} +% +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :return: +% The speed of sound. Units: m/s +% -if isIdealGas(a) - gamma = cp_mass(a)/cv_mass(a); - wtm = meanMolecularWeight(a); +if isIdealGas(tp) + gamma = cp_mass(tp)/cv_mass(tp); + wtm = meanMolecularWeight(tp); r = gasconstant/wtm; - b = sqrt(gamma * r * temperature(a)); + c = sqrt(gamma*r*temperature(tp)); else - rho0 = density(a); - p0 = pressure(a); - s0 = entropy_mass(a); + rho0 = density(tp); + p0 = pressure(tp); + s0 = entropy_mass(tp); rho1 = 1.001*rho0; - set(gas,'Density',rho1,'Entropy',s0); - p1 = pressure(a); + set(tp, 'Density', rho1, 'Entropy', s0); + p1 = pressure(tp); dpdrho_s = (p1 - p0)/(rho1 - rho0); - b = sqrt(dpdrho_s); + c = sqrt(dpdrho_s); end diff --git a/interfaces/matlab/toolbox/@ThermoPhase/speciesIndex.m b/interfaces/matlab/toolbox/@ThermoPhase/speciesIndex.m index 650e84d22..c76880c9e 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/speciesIndex.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/speciesIndex.m @@ -1,22 +1,28 @@ function k = speciesIndex(tp, name) -% SPECIESINDEX - The species index of species with name 'name'. +% SPECIESINDEX Get the index of a species given the name. +% k = speciesIndex(tp,name) +% The index is an integer assigned to each species in sequence as it +% is read in from the input file. % -% The index is an integer assigned to each species in sequence as it -% is read in from the input file. +% NOTE: In keeping with the conventions used by Matlab, this method +% returns 1 for the first species, 2 for the second, etc. In +% contrast, the corresponding method speciesIndex in the Cantera C++ +% and Python interfaces returns 0 for the first species, 1 for the +% second one, etc. :: % -% If name is a single string, the return value will be a integer -% containing the corresponding index. If it is an cell array of -% strings, the output will be an array of the same shape -% containing the indices. +% >> ich4 = speciesIndex(gas, 'CH4'); +% >> iho2 = speciesIndex(gas, 'HO2'); % -% NOTE: In keeping with the conventions used by Matlab, this method -% returns 1 for the first species, 2 for the second, etc. In -% contrast, the corresponding method speciesIndex in the Cantera C++ -% and Python interfaces returns 0 for the first species, 1 for the -% second one, etc. -% -% ich4 = speciesIndex(gas, 'CH4'); -% iho2 = speciesIndex(gas, 'HO2'); +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param name: +% If name is a single string, the return value will be a integer +% containing the corresponding index. If it is an cell array of +% strings, the output will be an array of the same shape +% containing the indices. +% :return: +% Scalar or array of integers % if iscell(name) diff --git a/interfaces/matlab/toolbox/@ThermoPhase/speciesName.m b/interfaces/matlab/toolbox/@ThermoPhase/speciesName.m index 7cfd1a2c9..7d3eb8eb0 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/speciesName.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/speciesName.m @@ -1,9 +1,13 @@ function nm = speciesName(tp, k) -% SPECIESNAME - Name of species k. -% If k is a scalar integer, the return value will be a string -% containing the name of the kth species. If it is an array of -% integers, the output will be a cell array of -% the same shape containing the name strings. +% SPECIESNAME Get the name of a species given the index. +% nm = speciesName(tp, k) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :param k: +% Scalar or array of integer species numbers +% :return: +% Cell array of strings % [m,n] = size(k); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/speciesNames.m b/interfaces/matlab/toolbox/@ThermoPhase/speciesNames.m index abfdecb53..0ff87a48a 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/speciesNames.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/speciesNames.m @@ -1,3 +1,11 @@ function n = speciesNames(tp) +% SPECIESNAMES Get the species names. +% n = speciesNames(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :return: +% Cell array of strings of all of the species names +% n = speciesName(tp, 1:nSpecies(tp)); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/temperature.m b/interfaces/matlab/toolbox/@ThermoPhase/temperature.m index 39e28f034..f4233e5f0 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/temperature.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/temperature.m @@ -1,4 +1,11 @@ function t = temperature(tp) -% TEMPERATURE - temperature [K]. +% TEMPERATURE Get the temperature. +% t = temperature(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :return: +% Temperature. Units: K +% t = phase_get(tp.tp_id, 1); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/thermalExpansionCoeff.m b/interfaces/matlab/toolbox/@ThermoPhase/thermalExpansionCoeff.m index 800759f8e..cd285022b 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/thermalExpansionCoeff.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/thermalExpansionCoeff.m @@ -1,9 +1,11 @@ function a = thermalExpansionCoeff(tp) -% THERMALEXPANSIONCOEFF - Thermal Expansion Coefficient [1/K] -% -% a = thermalExpansionCoeff(p) -% Return the thermal expansion coefficient of ThermoPhase p -% in units of 1/K +% THERMALEXPANSIONCOEFF Get the thermal expansion coefficient. +% a = thermalExpansionCoeff(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :return: +% Thermal Expansion Coefficient. Units: 1/K % a = thermo_get(tp.tp_id, 27); diff --git a/interfaces/matlab/toolbox/@ThermoPhase/thermo_hndl.m b/interfaces/matlab/toolbox/@ThermoPhase/thermo_hndl.m index 80c5c56e8..fcade2dce 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/thermo_hndl.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/thermo_hndl.m @@ -1,3 +1,12 @@ function i = thermo_hndl(tp) +% THERMO_HNDL Get the integer used to access the kernel object. +% i = thermo_hndl(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% object deriving from ThermoPhase) +% for which the handle is desired. +% :return: +% Integer used to access the kernel object. +% i = tp.tp_id; diff --git a/interfaces/matlab/toolbox/@ThermoPhase/vaporFraction.m b/interfaces/matlab/toolbox/@ThermoPhase/vaporFraction.m index 82706977a..6167f28eb 100644 --- a/interfaces/matlab/toolbox/@ThermoPhase/vaporFraction.m +++ b/interfaces/matlab/toolbox/@ThermoPhase/vaporFraction.m @@ -1,6 +1,11 @@ function v = vaporFraction(tp) -% VAPORFRACTION - Vapor fraction. -% If object 'a' represents a liquid/vapor mixture, this method -% returns the vapor fraction. +% VAPORFRACTION Get the vapor fraction. +% v = vaporFraction(tp) +% :param tp: +% Instance of class :mat:func:`ThermoPhase` (or another +% class derived from ThermoPhase) +% :return: +% Vapor fraction. +% v = thermo_get(tp.tp_id, 22); diff --git a/interfaces/matlab/toolbox/@Transport/Transport.m b/interfaces/matlab/toolbox/@Transport/Transport.m index 9995cf5c6..6f80d486c 100644 --- a/interfaces/matlab/toolbox/@Transport/Transport.m +++ b/interfaces/matlab/toolbox/@Transport/Transport.m @@ -1,29 +1,62 @@ -function tr = Transport(xml_phase, th, model, loglevel) -%TRANSPORT Transport class constructor. +function tr = Transport(r, th, model, loglevel) +% TRANSPORT Transport class constructor. +% tr = Transport(r, th, model, loglevel) +% Create a new instance of class :mat:func:`Transport`. One, three, +% or four arguments may be supplied. If one argument is given, +% it must be an instance of class :mat:func:`Transport`, and +% a copy will be returned. If three or four arguments are given, +% the first two must be an instance of class :mat:func:`XML_Node` +% and an instance of class :mat:func:`ThermoPhase` respectively. +% The third argument is the type of modeling desired, specified +% by the string ``'default'``, ``'Mix'`` or ``'Multi'``. +% ``'default'`` uses the default transport specified in the +% :mat:func:`XML_Node`. The fourth argument is +% the logging level desired. % -% k = TRANSPORT(model, p, loglevel) creates a transport -% manager for phase object p. -% -% The 'model' parameter is a string that specifies the transport -% model. The phase object must have already been created. +% :param r: +% Either an instance of class :mat:func:`Transport` or an +% instance of class :mat:func:`XML_Node` +% :param th: +% Instance of class :mat:func:`ThermoPhase` +% :param model: +% String indicating the transport model to use. Possible values +% are ``'default'``, ``'Mix'``, and ``'Multi'`` +% :param loglevel: +% Level of diagnostic logging. Default if not specified is 4. +% :return: +% Instance of class :mat:func:`Transport` % + tr.id = 0; -if nargin == 4 - tr.th = th; - if strcmp(model, 'default') - try - node = child(xml_phase, 'transport'); - tr.model = attrib(node, 'model'); - catch - tr.model = 'None'; - end +if nargin == 1 + if isa(r, 'Transport') + tr = r; else - tr.model = model; + error(['Unless the first argument is an instance of class ' ... + 'Transport, there must be more than one argument']) end - tr.id = trans_get(hndl(th), -1, tr.model, loglevel) ; - tr = class(tr, 'Transport'); -elseif isa(model, 'Transport') - tr = model; else - error('syntax error'); + if nargin == 3 + loglevel = 4; + end + if ~isa(r, 'XML_Node') + error(['The first argument must either be an instance of class ' ... + 'Transport or XML_Node']) + elseif ~isa(th, 'ThermoPhase') + error('The second argument must be an instance of class ThermoPhase') + else + tr.th = th; + if strcmp(model, 'default') + try + node = child(r, 'transport'); + tr.model = attrib(node, 'model'); + catch + tr.model = 'None'; + end + else + tr.model = model; + end + tr.id = trans_get(thermo_hndl(th), -1, tr.model, loglevel) ; + tr = class(tr, 'Transport'); + end end diff --git a/interfaces/matlab/toolbox/@Transport/binDiffCoeffs.m b/interfaces/matlab/toolbox/@Transport/binDiffCoeffs.m index 9a2c31d6b..75c847fcc 100644 --- a/interfaces/matlab/toolbox/@Transport/binDiffCoeffs.m +++ b/interfaces/matlab/toolbox/@Transport/binDiffCoeffs.m @@ -1,9 +1,13 @@ function v = binDiffCoeffs(a) -%BINDIFFCOEFFS Binary diffusion coefficients (m^2/s). -% -% d = binDiffCoeffs(gas) -% -% returns the matrix of binary diffusion coefficients in array -% d. The matrix is symmetric: d(i,j) = d(j,i). +% BINDIFFCOEFFS Get the binary diffusion coefficents. +% v = binDiffCoeffs(a) +% :param a: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% for which binary diffusion coefficients are desired. +% :return: +% A matrix of binary diffusion coefficients. +% The matrix is symmetric: d(i,j) = d(j,i). Units: m**2/s % + v = trans_get(a.id, 21, nSpecies(a.th)); diff --git a/interfaces/matlab/toolbox/@Transport/clear.m b/interfaces/matlab/toolbox/@Transport/clear.m index d8a20cc54..32aee1c05 100644 --- a/interfaces/matlab/toolbox/@Transport/clear.m +++ b/interfaces/matlab/toolbox/@Transport/clear.m @@ -1,3 +1,9 @@ function clear(tr) +% CLEAR Delete the Transport instance. +% clear(tr) +% :param tr: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% trans_get(tr.id, 0) diff --git a/interfaces/matlab/toolbox/@Transport/electricalConductivity.m b/interfaces/matlab/toolbox/@Transport/electricalConductivity.m index 8dd0234df..b395fcfad 100644 --- a/interfaces/matlab/toolbox/@Transport/electricalConductivity.m +++ b/interfaces/matlab/toolbox/@Transport/electricalConductivity.m @@ -1,5 +1,14 @@ function v = electricalConductivity(a) -% ELECTRICALCONDUCTIVITY Electrical conductivity in S/m. +% ELECTRICALCONDUCTIVITY Get the electrical conductivity. +% v = electricalConductivity(a) +% :param a: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% for which the electrical conductivity is desired. +% :return: +% Electrical conductivity in S/m +% + v = trans_get(a.id, 3); if v == -1.0 error(geterr); diff --git a/interfaces/matlab/toolbox/@Transport/hndl.m b/interfaces/matlab/toolbox/@Transport/hndl.m index 988ee5fab..9860a501b 100644 --- a/interfaces/matlab/toolbox/@Transport/hndl.m +++ b/interfaces/matlab/toolbox/@Transport/hndl.m @@ -1,4 +1,9 @@ function n = hndl(a) +% HNDL Get the integer used to access the kernel object. +% n = hndl(a) +% Integer used to access kernel objects. Deprecated in favor of +% :mat:func:`trans_hndl`. +% warning('This function is deprecated in favor of trans_hndl') n = a.id; diff --git a/interfaces/matlab/toolbox/@Transport/mixDiffCoeffs.m b/interfaces/matlab/toolbox/@Transport/mixDiffCoeffs.m index dfa7d1ddb..03daf9ee6 100644 --- a/interfaces/matlab/toolbox/@Transport/mixDiffCoeffs.m +++ b/interfaces/matlab/toolbox/@Transport/mixDiffCoeffs.m @@ -1,19 +1,27 @@ function v = mixDiffCoeffs(a) -%MIXDIFFCOEFFS Mixture-averaged diffusion coefficients (m^2/s). +% MIXDIFFCOEFFS Get the mixture-averaged diffusion coefficients. +% v = mixDiffCoeffs(a) +% Object ``a`` must belong to a class derived from +% Transport, and that was constructed by specifying the ``'Mix'`` +% option. If ``'Mix'`` was not specified, you will get the error message :: % -% d = mixDiffCoeffs(gas) +% **** Method getMixDiffCoeffs not implemented. **** % -% returns in column vector d the mixture-averaged diffusion -% coefficients. Object 'gas' must belong to a class derived from -% Transport, and that was constructed by specifying the 'Mix' -% option. If 'Mix' was not specified, you will get the error message +% In this case, try method :mat:func:`multiDiffCoeffs`, or create a +% new gas mixture model that uses a mixture-averaged transport manager, +% for example:: % -% **** Method getMixDiffCoeffs not implemented. **** +% >> gas = GRI30('Mix'); % -% In this case, try method 'multiDiffCoeffs', or create a new gas -% mixture model that uses a mixture-averaged transport manager, -% for example: +% See also: :mat:func:`MultiDiffCoeffs` % -% gas = GRI30('Mix') +% :param a: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% for which mixture-averaged diffusion coefficients are desired. +% :return: +% Vector of length nSpecies with the mixture-averaged diffusion +% coefficients. Units: m**2/s % + v = trans_get(a.id, 11, nSpecies(a.th)); diff --git a/interfaces/matlab/toolbox/@Transport/multiDiffCoeffs.m b/interfaces/matlab/toolbox/@Transport/multiDiffCoeffs.m index 915705443..fa3ee4044 100644 --- a/interfaces/matlab/toolbox/@Transport/multiDiffCoeffs.m +++ b/interfaces/matlab/toolbox/@Transport/multiDiffCoeffs.m @@ -1,20 +1,27 @@ function v = multiDiffCoeffs(a) -%MULTIDIFFCOEFFS Multicomponent diffusion coefficients (m^2/s). +% MULTIDIFFCOEFFS Get the multicomponent diffusion coefficients. +% v = multiDiffCoeffs(a) +% Object ``a`` must belong to a class derived from +% Transport, and that was constructed by specifying the ``'Multi'`` +% option. If ``'Multi'`` was not specified, you will get the +% error message :: % -% d = multiDiffCoeffs(gas) +% **** Method getMultiDiffCoeffs not implemented. **** % -% returns in d the array of multicomponent diffusion -% coefficients. Object 'gas' must belong to a class derived from -% Transport, and that was constructed by specifying the 'Multi' -% option. If 'Multi' was not specified, you will get the error message +% In this case, try method :mat:func:`mixDiffCoeffs`, or create a +% new gas mixture model that uses a mixture-averaged transport manager, +% for example:: % -% **** Method getMultiDiffCoeffs not implemented. **** +% >> gas = GRI30('Multi'); % -% In this case, try method 'mixDiffCoeffs', or create a new gas -% mixture model that uses a multicomponent transport manager, -% for example: -% -% gas = GRI30('Multi') +% :param a: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% for which multicomponent diffusion coefficients are desired. +% :return: +% Vector of length nSpecies with the multicomponent diffusion +% coefficients. Units: m**2/s % + v = trans_get(a.id, 22, nSpecies(a.th)); diff --git a/interfaces/matlab/toolbox/@Transport/setParameters.m b/interfaces/matlab/toolbox/@Transport/setParameters.m index a3d347c9d..6a05a6d47 100644 --- a/interfaces/matlab/toolbox/@Transport/setParameters.m +++ b/interfaces/matlab/toolbox/@Transport/setParameters.m @@ -1,4 +1,15 @@ function setParameters(tr, type, k, p) -% SETPARAMETERS - set parameters. +% SETPARAMETERS Set the parameters. +% setParameters(tr, type, k, p) +% Set parameters of the :mat:func:`Transport` instance. +% Not defined for all transport types. % +% :param tr: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% :param type: +% :param k: +% :param p: +% + v = trans_get(tr.id, 31, type, k, p); diff --git a/interfaces/matlab/toolbox/@Transport/setThermalConductivity.m b/interfaces/matlab/toolbox/@Transport/setThermalConductivity.m index 2f802acad..49b1e21b9 100644 --- a/interfaces/matlab/toolbox/@Transport/setThermalConductivity.m +++ b/interfaces/matlab/toolbox/@Transport/setThermalConductivity.m @@ -1,8 +1,15 @@ function setThermalConductivity(tr, lam) -% SETTHERMALCONDUCTIVITY - Set the thermal conductivity. +% SETTHERMALCONDUCTIVITY Set the thermal conductivity. +% setThermalConductivity(tr, lam) +% This method can only be used with transport models that +% support directly setting the value of the thermal +% conductivity. % -% This method can only be used with transport models that -% support directly setting the value of the thermal -% conductivity. +% :param tr: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% :param lam: +% Thermal conductivity in W/(m-K) % + setParameters(tr, 1, 0, lam); diff --git a/interfaces/matlab/toolbox/@Transport/thermalConductivity.m b/interfaces/matlab/toolbox/@Transport/thermalConductivity.m index 77b5ba19c..d22c54fc4 100644 --- a/interfaces/matlab/toolbox/@Transport/thermalConductivity.m +++ b/interfaces/matlab/toolbox/@Transport/thermalConductivity.m @@ -1,5 +1,14 @@ function v = thermalConductivity(a) -% THERMALCONDUCTIVITY Thermal conductivity in W/m^2/K. +% THERMALCONDUCTIVITY Get the thermal conductivity. +% v = thermalConductivity(a) +% :param a: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% for which the thermal conductivity is desired. +% :return: +% Thermal conductivity. Units: W/m-K +% + v = trans_get(a.id, 2); if v == -1.0 error(geterr); diff --git a/interfaces/matlab/toolbox/@Transport/thermalDiffCoeffs.m b/interfaces/matlab/toolbox/@Transport/thermalDiffCoeffs.m index 648063525..644ff68c4 100644 --- a/interfaces/matlab/toolbox/@Transport/thermalDiffCoeffs.m +++ b/interfaces/matlab/toolbox/@Transport/thermalDiffCoeffs.m @@ -1,12 +1,17 @@ function v = thermalDiffCoeffs(a) -%THERMALDIFFCOEFFS Thermal diffusion coefficients. +% THERMALDIFFCOEFFS Get the thermal diffusion coefficients. +% v = thermalDiffCoeffs(a) +% Object ``a`` must belong to a class derived from +% Transport, and that was constructed by specifying the ``'Multi'`` +% option. If ``'Multi'`` was not specified, the returned values will +% all be zero. % -% dt = thermalDiffCoeffs(gas) -% -% returns in column vector dt the thermal diffusion -% coefficients. Object 'gas' must belong to a class derived from -% Transport, and that was constructed by specifying the 'Multi' -% option. If 'Multi' was not specified, the returned values will -% all be zero. +% :param a: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% for which the thermal diffusion coefficients are desired. +% :return: +% Vector of thermal diffusion coefficients of length nSpecies % + v = trans_get(a.id, 12, nSpecies(a.th)); diff --git a/interfaces/matlab/toolbox/@Transport/trans_hndl.m b/interfaces/matlab/toolbox/@Transport/trans_hndl.m index ae8c76fc7..3cb0b0efb 100644 --- a/interfaces/matlab/toolbox/@Transport/trans_hndl.m +++ b/interfaces/matlab/toolbox/@Transport/trans_hndl.m @@ -1,2 +1,12 @@ function n = trans_hndl(a) +% TRANS_HNDL Get the integer used to access the kernel object. +% n = trans_hndl(a) +% :param a: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% for which the handle is desired. +% :return: +% Integer used to access the kernel object +% + n = a.id; diff --git a/interfaces/matlab/toolbox/@Transport/viscosity.m b/interfaces/matlab/toolbox/@Transport/viscosity.m index d732cebbc..609eced8a 100644 --- a/interfaces/matlab/toolbox/@Transport/viscosity.m +++ b/interfaces/matlab/toolbox/@Transport/viscosity.m @@ -1,4 +1,14 @@ function v = viscosity(a) +% VISCOSITY Get the dynamic viscosity. +% v = viscosity(a) +% :param a: +% Instance of class :mat:func:`Transport` (or another +% object derived from Transport) +% for which the viscosity is desired. +% :return: +% Dynamic viscosity. Units: Pa*s +% + v = trans_get(a.id, 1); if v == -1.0 error(geterr); diff --git a/interfaces/matlab/toolbox/@Wall/Wall.m b/interfaces/matlab/toolbox/@Wall/Wall.m index 383f59248..dde629bd3 100644 --- a/interfaces/matlab/toolbox/@Wall/Wall.m +++ b/interfaces/matlab/toolbox/@Wall/Wall.m @@ -1,5 +1,76 @@ function x = Wall(left, right, area, k, u, q, v, kleft, kright) +% WALL Wall class constructor. +% x = Wall(left, right, area, k, u, q, v, kleft, kright) +% 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 +% +% .. math:: v = K(P_{\rm left} - P_{\rm right}) + v_0(t), +% +% where :math:`K` is a non-negative constant, and :math:`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 +% +% .. math:: q = U(T_{\rm left} - T_{\rm right}) + q_0(t), +% +% where :math:`U` is the overall heat transfer coefficient for +% conduction/convection. The function +% :math:`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. +% +% A heterogeneous reaction mechanism may be specified for one or both of the +% wall surfaces. The mechanism object (typically an instance of class +% :mat:func:`Interface`) must be constructed so that it is properly linked to +% the object representing the fluid in the reactor the surface in question +% faces. The surface temperature on each side is taken to be equal to the +% temperature of the reactor it faces. +% +% Note: all of the arguments are optional and can be activated after initial +% construction by using the various methods of the :mat:func:`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. +% +% :param left: +% Instance of class :mat:func:`Reactor` to be used as the bulk phase on +% the left side of the wall. See :mat:func:`install` +% :param right: +% Instance of class :mat:func:`Reactor` to be used as the bulk phase on +% the right side of the wall. See :mat:func:`install` +% :param area: +% The area of the wall in m**2. See :mat:func:`area` and :mat:func:`setArea`. +% Defaults to 1.0 m**2 if not specified. +% :param k: +% Expansion rate coefficient in m/(s-Pa). See :mat:func:`setExpansionRateCoeff` +% and :mat:func:`vdot`. Defaults to 0.0 if not specified. +% :param u: +% Heat transfer coefficient in W/(m**2-K). See :mat:func:`setHeatTransferCoeff` +% and :mat:func:`qdot`. Defaults to 0.0 if not specified. +% :param q: +% Heat flux in W/m**2. Must be an instance of :mat:func:`Func`. See +% :mat:func:`setHeatFlux` and :mat:func:`qdot`. Defaults to 0.0 if not specified. +% :param v: +% Velocity of the wall in m/s. Must be an instance of :mat:func:`Func`. See +% :mat:func:`setVelocity` and :mat:func:`vdot`. Defaults to 0.0 if not specified. +% :param kleft: +% Surface reaction mechanisms for the left-facing surface. This must be an +% instance of class :mat:func:`Kinetics`, or of a class derived from Kinetics, +% such as :mat:func:`Interface`. +% :param kright: +% Surface reaction mechanisms for the right-facing surface. This must be an +% instance of class :mat:func:`Kinetics`, or of a class derived from Kinetics, +% such as :mat:func:`Interface`. +% :return: +% Instance of class :mat:func:`Wall` % This is a dummy argument, it is not actually used by wall_new in ctreactor.cpp typ = 1; diff --git a/interfaces/matlab/toolbox/@Wall/area.m b/interfaces/matlab/toolbox/@Wall/area.m index ed6c6f83a..cc536f43d 100644 --- a/interfaces/matlab/toolbox/@Wall/area.m +++ b/interfaces/matlab/toolbox/@Wall/area.m @@ -1,4 +1,10 @@ function a = area(w) -% AREA - +% AREA Get the area of the wall. +% a = area(w) +% :param w: +% Instance of class :mat:func:`Wall` +% :return: +% Area of the wall in m**2 % + a = wallmethods(23, wall_hndl(w)); diff --git a/interfaces/matlab/toolbox/@Wall/install.m b/interfaces/matlab/toolbox/@Wall/install.m index 9c74043ff..1647e7163 100644 --- a/interfaces/matlab/toolbox/@Wall/install.m +++ b/interfaces/matlab/toolbox/@Wall/install.m @@ -1,6 +1,16 @@ function install(w, left, right) -% INSTALL - +% INSTALL Install a wall between two reactors. +% install(w, left, right) +% :param w: +% Instance of class :mat:func:`Wall` +% :param left: +% Instance of class :mat:func:`Reactor`or +% :mat:func:`Reservoir` +% :param right: +% Instance of class :mat:func:`Reactor` or +% :mat:func:`Reservoir` % + w.left = left; w.right = right; wallmethods(4, wall_hndl(w), reactor_hndl(left), reactor_hndl(right)); diff --git a/interfaces/matlab/toolbox/@Wall/qdot.m b/interfaces/matlab/toolbox/@Wall/qdot.m index 6d5d1391f..ff7e6c13b 100644 --- a/interfaces/matlab/toolbox/@Wall/qdot.m +++ b/interfaces/matlab/toolbox/@Wall/qdot.m @@ -1,3 +1,15 @@ function q = qdot(w, t) +% QDOT Get the total heat transfer through a wall given a time. +% q = qdot(w, t) +% A positive value corresponds to heat flowing from the left-hand +% reactor to the right-hand one. +% +% :param w: +% Instance of class :mat:func:`Wall` +% :param t: +% Time at which the heat transfer should be evaluated. +% :return: +% Total heat transfer. Units: W +% q = wallmethods(22, wall_hndl(w), t); diff --git a/interfaces/matlab/toolbox/@Wall/ready.m b/interfaces/matlab/toolbox/@Wall/ready.m index a1fe512c6..a1f3c4727 100644 --- a/interfaces/matlab/toolbox/@Wall/ready.m +++ b/interfaces/matlab/toolbox/@Wall/ready.m @@ -1,4 +1,10 @@ function ok = ready(w) -% READY - +% READY Check whether a wall is ready. +% ok = ready(w) +% :param w: +% Instance of class :mat:func:`Wall` +% :return: +% Status of the wall % + ok = wallmethods(11, wall_hndl(w)); diff --git a/interfaces/matlab/toolbox/@Wall/setArea.m b/interfaces/matlab/toolbox/@Wall/setArea.m index cfd6762e8..ec0b18fe9 100644 --- a/interfaces/matlab/toolbox/@Wall/setArea.m +++ b/interfaces/matlab/toolbox/@Wall/setArea.m @@ -1,4 +1,10 @@ function setArea(w, a) -% SETAREA - +% SETAREA Set the area of a wall. +% setArea(w, a) +% :param w: +% Instance of class :mat:func:`Wall` +% :param a: +% Double area of the wall. % + wallmethods(5, wall_hndl(w), a); diff --git a/interfaces/matlab/toolbox/@Wall/setExpansionRateCoeff.m b/interfaces/matlab/toolbox/@Wall/setExpansionRateCoeff.m index 0fd625e30..9d7692eae 100644 --- a/interfaces/matlab/toolbox/@Wall/setExpansionRateCoeff.m +++ b/interfaces/matlab/toolbox/@Wall/setExpansionRateCoeff.m @@ -1,4 +1,20 @@ function setExpansionRateCoeff(w, k) -% SETEXPANSIONRATECOEFF - +% SETEXPANSIONRATECOEFF Set the expansion rate coefficient. +% setExpansionRateCoeff(w, k) +% 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 % +% .. math:: v = K(P_{left}-P_{right}) +% +% where :math:`v` is velocity, :math:`K` is the expansion rate +% coefficient, and :math:`P` is the pressure. +% +% :param w: +% Instance of class :mat:func:`Wall` +% :param k: +% Double, wall expansion rate coefficient. Units: m/(s-Pa) +% + wallmethods(9, wall_hndl(w), k); diff --git a/interfaces/matlab/toolbox/@Wall/setHeatFlux.m b/interfaces/matlab/toolbox/@Wall/setHeatFlux.m index 191d15004..6fabd5b15 100644 --- a/interfaces/matlab/toolbox/@Wall/setHeatFlux.m +++ b/interfaces/matlab/toolbox/@Wall/setHeatFlux.m @@ -1,4 +1,24 @@ function setHeatFlux(w, f) -% SET HEAT FLUX - +% SETHEATFLUX Set the heat flux using :mat:func:`Func` +% setHeatFlux(w, f) +% Must be set by an instance of +% class :mat:func:`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: % +% .. code-block:: matlab +% +% 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. +% +% :param w: +% Instance of class :mat:func:`Wall` +% :param f: +% Instance of class :mat:func:`Func`. Units: W/m**2 +% + wallmethods(8, wall_hndl(w), func_hndl(f)); diff --git a/interfaces/matlab/toolbox/@Wall/setHeatTransferCoeff.m b/interfaces/matlab/toolbox/@Wall/setHeatTransferCoeff.m index 3416ce6e5..3b9f76fa8 100644 --- a/interfaces/matlab/toolbox/@Wall/setHeatTransferCoeff.m +++ b/interfaces/matlab/toolbox/@Wall/setHeatTransferCoeff.m @@ -1,4 +1,10 @@ function setHeatTransferCoeff(w, u) -% SETHEATTRANSFERCOEFF - +% SETHEATTRANSFERCOEFF Set the heat transfer coefficient. +% setHeatTransferCoeff(w, u) +% :param w: +% Instance of class :mat:func:`Wall` +% :param u: +% Heat transfer coefficient of the wall. Units: W/(m**2-K) % + wallmethods(7, wall_hndl(w), u); diff --git a/interfaces/matlab/toolbox/@Wall/setKinetics.m b/interfaces/matlab/toolbox/@Wall/setKinetics.m index 04c5ed08d..a09dc0cdf 100644 --- a/interfaces/matlab/toolbox/@Wall/setKinetics.m +++ b/interfaces/matlab/toolbox/@Wall/setKinetics.m @@ -1,6 +1,20 @@ function setKinetics(w, left, right) -% SETKINETICS - Specify the left and right surface reaction mechanisms. +% SETKINETICS Set the surface reaction mechanisms on a wall. +% setKinetics(w, left, right) +% :param w: +% Instance of class :mat:func:`Wall` +% :param left: +% Instance of class :mat:func:`Kinetics` (or another object +% derived from Kinetics) to be used as the +% surface kinetics for the left side of the wall. Typically +% an instance of class :mat:func:`Interface` +% :param right: +% Instance of class :mat:func:`Kinetics` (or another object +% derived from Kinetics) to be used as the +% surface kinetics for the right side of the wall. Typically +% an instance of class :mat:func:`Interface` % + ileft = 0; iright = 0; if isa(left, 'Kinetics') diff --git a/interfaces/matlab/toolbox/@Wall/setThermalResistance.m b/interfaces/matlab/toolbox/@Wall/setThermalResistance.m index 94d8cbc2b..525afab85 100644 --- a/interfaces/matlab/toolbox/@Wall/setThermalResistance.m +++ b/interfaces/matlab/toolbox/@Wall/setThermalResistance.m @@ -1,4 +1,10 @@ function setThermalResistance(w, r) -% SETTHERMALRESISTANCE - +% SETTHERMALRESISTANCE Set the thermal resistance. +% setThermalResistance(w, r) +% :param w: +% Instance of class :mat:func:`Wall` +% :param r: +% Double, thermal resistance. Units: K*m**2/W % + wallmethods(6, wall_hndl(w), r) diff --git a/interfaces/matlab/toolbox/@Wall/setVelocity.m b/interfaces/matlab/toolbox/@Wall/setVelocity.m index 59b273b70..bb64b62ed 100644 --- a/interfaces/matlab/toolbox/@Wall/setVelocity.m +++ b/interfaces/matlab/toolbox/@Wall/setVelocity.m @@ -1,4 +1,23 @@ function setVelocity(w, f) -% SET VELOCITY - +% SETVELOCITY Set the velocity of the wall using :mat:func:`Func`. +% setVelocity(w, f) +% Must be set by an instance of class :mat:func:`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: % +% .. code-block:: matlab +% +% w = Wall() +% f = Func('polynomial',0,10); % Or f = polynom(10); +% setVelocity(w, f); +% +% sets the velocity of the wall to 10 m/s. +% +% :param w: +% Instance of class :mat:func:`Wall` +% :param f: +% Instance of class :mat:func:`Func`. Units: m/s +% + wallmethods(10, wall_hndl(w), func_hndl(f)); diff --git a/interfaces/matlab/toolbox/@Wall/vdot.m b/interfaces/matlab/toolbox/@Wall/vdot.m index ec1f1ec73..b9cce2aee 100644 --- a/interfaces/matlab/toolbox/@Wall/vdot.m +++ b/interfaces/matlab/toolbox/@Wall/vdot.m @@ -1,3 +1,15 @@ function v = vdot(w, t) +% VDOT Get the rate of volumetric change at a given time. +% v = vdot(w, t) +% A positive value corresponds to the left-hand reactor volume +% increasing, and the right-hand reactor volume decreasing. +% +% :param w: +% Instance of class :mat:func:`Wall` +% :param t: +% Time at which the volumetric change should be calculated. +% :return: +% Rate of volumetric change Units: m**3/s +% v = wallmethods(21, wall_hndl(w), t); diff --git a/interfaces/matlab/toolbox/@Wall/wall_hndl.m b/interfaces/matlab/toolbox/@Wall/wall_hndl.m index 808b4163d..d5eecb267 100644 --- a/interfaces/matlab/toolbox/@Wall/wall_hndl.m +++ b/interfaces/matlab/toolbox/@Wall/wall_hndl.m @@ -1,4 +1,11 @@ function i = wall_hndl(w) -% WALL_HNDL - +% WALL_HNDL Get the integer used to access the kernel object. +% i = wall_hndl(w) +% :param w: +% Instance of class :mat:func:`Wall` +% for which the handle is desired. +% :return: +% Integer used to access the kernel object % + i = w.index; diff --git a/interfaces/matlab/toolbox/@XML_Node/XML_Node.m b/interfaces/matlab/toolbox/@XML_Node/XML_Node.m index 1a614d480..02b20a24b 100644 --- a/interfaces/matlab/toolbox/@XML_Node/XML_Node.m +++ b/interfaces/matlab/toolbox/@XML_Node/XML_Node.m @@ -1,6 +1,15 @@ function x = XML_Node(name, src, wrap) -% -% XML_Node - Cantera XML_Node class constructor +% XML_NODE XML_Node class constructor +% x = XML_Node(name, src, wrap) +% :param name: +% String name of the XML_Node that should be created. +% :param src: +% String XML file name from which an instance of XML_Node +% should be created. Reads the XML tree from the input file. +% :param wrap: +% Specify the ID of the XML_Node. +% :return: +% Instance of class :mat:func:`XML_Node` % x.id = 0; diff --git a/interfaces/matlab/toolbox/@XML_Node/addChild.m b/interfaces/matlab/toolbox/@XML_Node/addChild.m index 59745f6ef..f484eaa63 100644 --- a/interfaces/matlab/toolbox/@XML_Node/addChild.m +++ b/interfaces/matlab/toolbox/@XML_Node/addChild.m @@ -1,3 +1,14 @@ -function n = addChild(root, id, val) +function n = addChild(root, name, val) +% ADDCHILD Add a child to the root. +% n = addChild(root, name, val) +% :param root: +% Instance of class :mat:func:`XML_Node` +% :param name: +% String ID of the child to be added. +% :param val: +% String value to be added to the child. +% :return: +% Instance of class :mat:func:`XML_Node` % -n = ctmethods(10, 11, root.id, id, val); + +n = ctmethods(10, 11, root.id, name, val); diff --git a/interfaces/matlab/toolbox/@XML_Node/attrib.m b/interfaces/matlab/toolbox/@XML_Node/attrib.m index 728033c83..c06de2527 100644 --- a/interfaces/matlab/toolbox/@XML_Node/attrib.m +++ b/interfaces/matlab/toolbox/@XML_Node/attrib.m @@ -1,4 +1,13 @@ function a = attrib(x, key) +% ATTRIB Get the XML_Node attribute with a given key. +% a = attrib(x, key) +% :param x: +% Instance of class :mat:func:`XML_Node` +% :param key: +% String key to look up. +% :return: +% Instance of class :mat:func:`XML_Node` +% if nargin ~= 2 || ~isa(key, 'char') error('Syntax error. Type "help attrib" for more information.') diff --git a/interfaces/matlab/toolbox/@XML_Node/build.m b/interfaces/matlab/toolbox/@XML_Node/build.m index feae88913..957661d5f 100644 --- a/interfaces/matlab/toolbox/@XML_Node/build.m +++ b/interfaces/matlab/toolbox/@XML_Node/build.m @@ -1,4 +1,17 @@ function x = build(x, file, pre) +% BUILD Build an XML_Node in memory from an input file. +% x = build(x, file, pre) +% :param x: +% Instance of class :mat:func:`XML_Node` +% :param file: +% String input file name. +% :param pre: +% Determine the method of building. If not specified or +% less than zero, use XML_Node::build. Otherwise, use +% XML_Node::get_XML_File. +% :return: +% Instance of class :mat:func:`XML_Node` +% if nargin < 2 || ~isa(file, 'char') error('Syntax error. Type "help build" for more information.') diff --git a/interfaces/matlab/toolbox/@XML_Node/child.m b/interfaces/matlab/toolbox/@XML_Node/child.m index 72c076fb5..4d128ad74 100644 --- a/interfaces/matlab/toolbox/@XML_Node/child.m +++ b/interfaces/matlab/toolbox/@XML_Node/child.m @@ -1,4 +1,13 @@ function v = child(x, loc) +% CHILD Get the child of an XML_Node instance. +% v = child(x, loc) +% :param x: +% Instance of class :mat:func:`XML_Node` +% :param loc: +% String loc to search for. +% :return: +% Instance of class :mat:func:`XML_Node` +% id = ctmethods(10, 6, x.id, loc); v = XML_Node('', '', id); diff --git a/interfaces/matlab/toolbox/@XML_Node/findByID.m b/interfaces/matlab/toolbox/@XML_Node/findByID.m index e18757d02..216284645 100644 --- a/interfaces/matlab/toolbox/@XML_Node/findByID.m +++ b/interfaces/matlab/toolbox/@XML_Node/findByID.m @@ -1,5 +1,12 @@ function x = findByID(root, id) -% FINDBYID - Find an XML element by ID +% FINDBYID Get an XML element given its ID. +% x = findByID(root, id) +% :param root: +% Instance of class :mat:func:`XML_Node` +% :param id: +% String ID of the element to search for. +% :return: +% Instance of class :mat:func:`XML_Node` % index = ctmethods(10, 8, root.id, id); diff --git a/interfaces/matlab/toolbox/@XML_Node/findByName.m b/interfaces/matlab/toolbox/@XML_Node/findByName.m index c068efa86..c1537f563 100644 --- a/interfaces/matlab/toolbox/@XML_Node/findByName.m +++ b/interfaces/matlab/toolbox/@XML_Node/findByName.m @@ -1,5 +1,12 @@ function x = findByName(root, name) -% FINDBYNAME - Find an XML element by name +% FINDBYNAME Get an XML element given its name. +% x = findByName(root, name) +% :param root: +% Instance of class :mat:func:`XML_Node` +% :param name: +% String name of the element to search for. +% :return: +% Instance of class :mat:func:`XML_Node` % index = ctmethods(10, 9, root.id, name); diff --git a/interfaces/matlab/toolbox/@XML_Node/hndl.m b/interfaces/matlab/toolbox/@XML_Node/hndl.m index 06165df2c..106b7fa86 100644 --- a/interfaces/matlab/toolbox/@XML_Node/hndl.m +++ b/interfaces/matlab/toolbox/@XML_Node/hndl.m @@ -1,4 +1,9 @@ function i = hndl(x) +% HNDL Get the integer used to access the kernel object. +% i = hndl(x) +% Integer used to access kernel objects. Deprecated in favor of +% :mat:func:`xml_hndl`. +% warning('This function is deprecated in favor of xml_hndl.m') i = x.id; diff --git a/interfaces/matlab/toolbox/@XML_Node/nChildren.m b/interfaces/matlab/toolbox/@XML_Node/nChildren.m index a76484d5c..5c14e2415 100644 --- a/interfaces/matlab/toolbox/@XML_Node/nChildren.m +++ b/interfaces/matlab/toolbox/@XML_Node/nChildren.m @@ -1,3 +1,10 @@ function n = nChildren(root) +% NCHILDREN Get the number of children of an XML_Node. +% n = nChildren(root) +% :param root: +% Instance of class :mat:func:`XML_Node` +% :return: +% Integer number of children of the input XML_Node % + n = ctmethods(10, 10, root.id); diff --git a/interfaces/matlab/toolbox/@XML_Node/value.m b/interfaces/matlab/toolbox/@XML_Node/value.m index 7e6c3c655..ed2326ed4 100644 --- a/interfaces/matlab/toolbox/@XML_Node/value.m +++ b/interfaces/matlab/toolbox/@XML_Node/value.m @@ -1,7 +1,16 @@ function v = value(x, loc) -% VALUE - value(x) returns the value of the XML element. -% value(x, loc) is shorthand for value(child(x,loc)) +% VALUE Get the value at a location in an XML_Node +% v = value(x,loc) +% value(x) returns the value of the XML element. +% value(x, loc) is shorthand for value(child(x,loc)) % +% :param x: +% Instance of class :mat:func:`XML_Node` +% :param loc: +% :return: +% Instance of class :mat:func:`XML_Node` +% + if nargin == 2 c = child(x, loc); id = c.id; diff --git a/interfaces/matlab/toolbox/@XML_Node/write.m b/interfaces/matlab/toolbox/@XML_Node/write.m index 39034216a..9c66bc00c 100644 --- a/interfaces/matlab/toolbox/@XML_Node/write.m +++ b/interfaces/matlab/toolbox/@XML_Node/write.m @@ -1,3 +1,13 @@ function write(x, file) +% WRITE Write XML_Node to file. +% write(x, file) +% +% :param x: +% Instance of class :mat:func:`XML_Node` +% :param file: +% Name of the output file to be written. +% :return: +% Instance of class :mat:func:`XML_Node` +% ctmethods(10, 13, x.id, file); diff --git a/interfaces/matlab/toolbox/@XML_Node/xml_hndl.m b/interfaces/matlab/toolbox/@XML_Node/xml_hndl.m index bf83949fd..d5f65afd4 100644 --- a/interfaces/matlab/toolbox/@XML_Node/xml_hndl.m +++ b/interfaces/matlab/toolbox/@XML_Node/xml_hndl.m @@ -1,3 +1,12 @@ function i = xml_hndl(x) +% XML_HNDL Get the integer used to access the kernel object. +% i = xml_hndl(x) +% +% :param x: +% Instance of class :mat:func:`XML_Node` +% for which the handle is desired. +% :return: +% Integer used to access the kernel object +% -i = x.id; \ No newline at end of file +i = x.id; diff --git a/interfaces/matlab/toolbox/ConstPressureReactor.m b/interfaces/matlab/toolbox/ConstPressureReactor.m index dff13aeed..18987968c 100644 --- a/interfaces/matlab/toolbox/ConstPressureReactor.m +++ b/interfaces/matlab/toolbox/ConstPressureReactor.m @@ -1,15 +1,25 @@ function r = ConstPressureReactor(contents) -% CONSTPRESSUREREACTOR - Create a ConstPressureReactor object. +% CONSTPRESSUREREACTOR Create a constant pressure reactor object. +% r = ConstPressureReactor(contents) +% A :mat:func:`ConstPressureReactor` is an instance of class +% :mat:func:`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: % -% 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. +% .. code-block:: matlab % -% r1 = ConstPressureReactor % an empty reactor -% r2 = ConstPressureReactor(gas) % a reactor containing a gas +% r1 = ConstPressureReactor % an empty reactor +% r2 = ConstPressureReactor(contents) % a reactor containing contents % -% See also: Reactor +% See also: :mat:func:`Reactor` % +% :param contents: +% Cantera :mat:func:`Solution` to be set as the contents of the +% reactor +% :return: +% Instance of class :mat:func:`Reactor` +% + if nargin == 0 contents = 0; end diff --git a/interfaces/matlab/toolbox/FlowReactor.m b/interfaces/matlab/toolbox/FlowReactor.m index 9c27e55a3..07cb67a84 100644 --- a/interfaces/matlab/toolbox/FlowReactor.m +++ b/interfaces/matlab/toolbox/FlowReactor.m @@ -1,13 +1,23 @@ function r = FlowReactor(contents) -% FLOWREACTOR - Create a FlowReactor object. +% FLOWREACTOR Create a flow reactor object. +% r = FlowReactor(contents) +% A reactor representing adiabatic plug flow in a constant-area +% duct. Examples: % -% A reactor representing adiabatic plug flow in a constant-area duct. +% .. code-block:: matlab % -% r1 = FlowReactor % an empty reactor -% r2 = FlowReactor(gas) % a reactor containing a gas +% r1 = FlowReactor % an empty reactor +% r2 = FlowReactor(gas) % a reactor containing a gas % -% See also: Reactor +% See also: :mat:func:`Reactor` % +% :param contents: +% Cantera :mat:func:`Solution` to be set as the contents of the +% reactor +% :return: +% Instance of class :mat:func:`Reactor` +% + if nargin == 0 contents = 0; end diff --git a/interfaces/matlab/toolbox/GRI30.m b/interfaces/matlab/toolbox/GRI30.m index bc9a8b1b3..9831722a2 100755 --- a/interfaces/matlab/toolbox/GRI30.m +++ b/interfaces/matlab/toolbox/GRI30.m @@ -1,23 +1,34 @@ function s = GRI30(tr) -% GRI30 - Create a Solution instance representing -% reaction mechanism GRI-Mech 3.0. +% GRI30 Create an object with the GRI-Mech 3.0 reaction mechanism. +% s = GRI30(tr) +% Create a Solution instance representing +% reaction mechanism GRI-Mech 3.0. % -% GRI-Mech 3.0 is a widely-used reaction mechanism for natural gas -% combustion. It contains 53 species composed of the elements H, -% C, O, N, and/or Ar, and 325 reactions, most of which are -% reversible. GRI-Mech 3.0, like most combustion mechanisms, is -% designed for use at pressures where the ideal gas law holds. +% GRI-Mech 3.0 is a widely-used reaction mechanism for natural gas +% combustion. It contains 53 species composed of the elements H, +% C, O, N, and/or Ar, and 325 reactions, most of which are +% reversible. GRI-Mech 3.0, like most combustion mechanisms, is +% designed for use at pressures where the ideal gas law holds. +% GRI-Mech 3.0 is available from http://www.me.berkeley.edu/gri_mech/ % -% Function GRI30 creates the solution according to the -% specifications in file gri30.cti. The ideal gas equation of -% state is used. Transport property evaluation is disabled by -% default. To enable transport properties, supply the name of -% the transport model to use. +% Function :mat:func:`GRI30` creates the solution according to the +% specifications in file gri30.cti. The ideal gas equation of +% state is used. Transport property evaluation is disabled by +% default. To enable transport properties, supply the name of +% the transport model to use. +% +% .. code-block:: matlab % % g1 = GRI30 % no transport properties % g2 = GRI30('Mix') % mixture-averaged transport properties % g3 = GRI30('Multi') % miulticomponent transport properties % +% :param tr: +% Transport modeling, 'Mix' or 'Multi' +% :return: +% Instance of class :mat:func:`Solution` +% + if nargin == 0 s = Solution('gri30.cti', 'gri30'); elseif nargin == 1 diff --git a/interfaces/matlab/toolbox/Hydrogen.m b/interfaces/matlab/toolbox/Hydrogen.m index b54dda2f7..2e2d833cb 100644 --- a/interfaces/matlab/toolbox/Hydrogen.m +++ b/interfaces/matlab/toolbox/Hydrogen.m @@ -1,14 +1,20 @@ function h = Hydrogen() -% HYDROGEN - Return an object representing hydrogen. +% HYDROGEN Return an object representing hydrogen. +% h = Hydrogen() +% The object returned by this method implements an accurate equation of +% state for hydrogen that can be used in the liquid, vapor, saturated +% liquid/vapor, and supercritical regions of the phase diagram. The +% equation of state is taken from % -% The object returned by this method implements an accurate equation of -% state for hydrogen that can be used in the liquid, vapor, saturated -% liquid/vapor, and supercritical regions of the phase diagram. The -% equation of state is taken from W. C. Reynolds, "Thermodynamic -% Properties in SI." +% Reynolds, W. C. *Thermodynamic Properties in SI: graphs, tables, and +% computational equations for forty substances* Stanford: Stanford +% University, 1979. Print. % -% For more details, see classes Cantera::PureFluid and tpx::hydrogen in the -% Cantera C++ source code documentation. +% For more details, see classes Cantera::PureFluid and tpx::hydrogen in the +% Cantera C++ source code documentation. +% +% :return: +% Instance of class :mat:func:`Solution` % h = Solution('liquidvapor.cti', 'hydrogen'); diff --git a/interfaces/matlab/toolbox/IdealGasConstPressureReactor.m b/interfaces/matlab/toolbox/IdealGasConstPressureReactor.m index 0f7024f3c..80f9db1ff 100644 --- a/interfaces/matlab/toolbox/IdealGasConstPressureReactor.m +++ b/interfaces/matlab/toolbox/IdealGasConstPressureReactor.m @@ -1,18 +1,27 @@ function r = IdealGasConstPressureReactor(contents) -% IDEALGASCONSTPRESSUREREACTOR - Create an IdealGasConstPressureReactor object. +% IDEALGASCONSTPRESSUREREACTOR Create a constant pressure reactor with an ideal gas. +% r = IdealGasConstPressureReactor(contents) +% 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: % -% 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). +% .. code-block:: matlab % -% r1 = IdealGasConstPressureReactor % an empty reactor -% r2 = IdealGasConstPressureReactor(gas) % a reactor containing a gas +% r1 = IdealGasConstPressureReactor % an empty reactor +% r2 = IdealGasConstPressureReactor(gas) % a reactor containing a gas % -% See also: Reactor +% See also: :mat:func:`Reactor` % +% :param contents: +% Cantera :mat:func:`Solution` to be set as the contents of the +% reactor +% :return: +% Instance of class :mat:func:`Reactor` +% + if nargin == 0 contents = 0; end diff --git a/interfaces/matlab/toolbox/IdealGasMix.m b/interfaces/matlab/toolbox/IdealGasMix.m index 6786e9e72..621bb9706 100755 --- a/interfaces/matlab/toolbox/IdealGasMix.m +++ b/interfaces/matlab/toolbox/IdealGasMix.m @@ -1,35 +1,50 @@ function s = IdealGasMix(infile, b, c) -% IDEALGASMIX - Create a Solution instance representing an ideal gas mixture. +% IDEALGASMIX Create a mixture of ideal gases. +% s = IdealGasMix(infile, b, c) +% Create a :mat:func:`Solution` instance representing an ideal gas mixture. :: % -% gas1 = IdealGasMix('ctml_file'[,'transport_model']) -% gas2 = IdealGasMix('ck_file'[,'thermo_db'[,'tran_db'[,'transport_model']]]) +% gas1 = IdealGasMix('ctml_file'[,'transport_model']) +% gas2 = IdealGasMix('ck_file'[,'thermo_db'[,'tran_db'[,'transport_model']]]) % -% creates an object that represents an ideal gas mixture. The -% species in the mixture, their properties, and the reactions among -% the species, if any, are specified in file 'input_file'. Two -% input file formats are supported - CTML and CK -% (Chemkin-compatible). Examples: +% creates an object that represents an ideal gas mixture. The +% species in the mixture, their properties, and the reactions among +% the species, if any, are specified in file 'ctml_file' and 'ck_file'. Two +% input file formats are supported - CTML and CK +% (CHEMKIN-compatible). Examples:: % % g1a = IdealGasMix('mech.xml') -% g1b = IdealGasMix('mech.xml','Multi') +% g1b = IdealGasMix('mech.xml', 'Multi') % g2 = IdealGasMix('mech2.inp') -% g3 = IdealGasMix('mech3.inp','therm.dat') -% g4 = IdealGasMix('mech4.inp','therm.dat','tran.dat','Mix') +% g3 = IdealGasMix('mech3.inp', 'therm.dat') +% g4 = IdealGasMix('mech4.inp', 'therm.dat', 'tran.dat') % -% Objects g1a and g1b are created from a CTML file. CTML files -% contain all data required to build the object, and do not require -% any additional database files. Objects g2 - g4 are created from -% CK-format input files. For g2, 'mech2.inp' contains all required -% species thermo data. File 'mech3.inp' is missing some or all -% species thermo data, and requires database file 'therm.dat.' -% Object g4 is created including transport data. +% Objects ``g1a`` and ``g1b`` are created from a CTML file. CTML files +% contain all data required to build the object, and do not require +% any additional database files. Objects ``g2`` - ``g4`` are created +% from CK-format input files. For ``g2``, 'mech2.inp' contains all required +% species thermo data. File 'mech3.inp' is missing some or all +% species thermo data, and requires database file 'therm.dat.' +% Object ``g4`` is created including transport data. % -% Note that calling IdealGasMix with a CK-format input file -% also creates an equivalent CTML file that may be used in future -% calls. If the initial call includes a transport database, then -% the CTML file will contain transport data. +% Note that calling :mat:func:`IdealGasMix` with a CK-format input file +% also creates an equivalent CTML file that may be used in future +% calls. If the initial call includes a transport database, then +% the CTML file will contain transport data. % -% See also: ck2cti, Solution +% See also: :mat:func:`ck2cti`, :mat:func:`Solution` +% +% :param infile: +% Input file, either CTI, CTML, or CHEMKIN format +% :param b: +% If a CTI or CTML file is specified with ``infile``, this can be +% the transport modeling to be used. If a CHEMKIN format file is +% specified with ``infile``, this is the filename of the +% thermodynamic database, if required. +% :param c: +% If a CHEMKIN format file is specified with ``infile``, this is the +% filename of the transport database, if required. +% :return: +% Instance of class :mat:func:`Solution` % dotloc = findstr(infile, '.'); diff --git a/interfaces/matlab/toolbox/IdealGasReactor.m b/interfaces/matlab/toolbox/IdealGasReactor.m index 478d0aa65..842705398 100644 --- a/interfaces/matlab/toolbox/IdealGasReactor.m +++ b/interfaces/matlab/toolbox/IdealGasReactor.m @@ -1,15 +1,24 @@ function r = IdealGasReactor(contents) -% IDEALGASREACTOR - Create an IdealGasReactor object. +% IDEALGASREACTOR Create a reactor with an ideal gas. +% r = IdealGasReactor(contents) +% 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: % -% 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). +% .. code-block:: matlab % -% r1 = IdealGasReactor % an empty reactor -% r2 = IdealGasReactor(gas) % a reactor containing a gas +% r1 = IdealGasReactor % an empty reactor +% r2 = IdealGasReactor(gas) % a reactor containing a gas % -% See also: Reactor +% See also: :mat:func:`Reactor` % +% :param contents: +% Cantera :mat:func:`Solution` to be set as the contents of the +% reactor +% :return: +% Instance of class :mat:func:`Reactor` +% + if nargin == 0 contents = 0; end diff --git a/interfaces/matlab/toolbox/MassFlowController.m b/interfaces/matlab/toolbox/MassFlowController.m index 1e6ae5cf8..ae3708d64 100644 --- a/interfaces/matlab/toolbox/MassFlowController.m +++ b/interfaces/matlab/toolbox/MassFlowController.m @@ -1,18 +1,24 @@ function m = MassFlowController(upstream, downstream) +% MASSFLOWCONTROLLER Create a mass flow controller. +% m = MassFlowController(upstream, downstream) +% Creates an instance of class :mat:func:`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 :mat:func:`install` method +% should be used to install the :mat:func:`MassFlowController` between +% reactors. % -% MASSFLOWCONTROLLER - Create a mass flow controller connecting two -% reactors / reservoirs. +% see also: :mat:func:`FlowDevice`, :mat:func:`Valve` % -% m = MassFlowController(upstream, downstream) -% -% 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. -% -% see also: FlowDevice +% :param upstream: +% Upstream :mat:func:`Reactor` or :mat:func:`Reservoir` +% :param downstream: +% Downstream :mat:func:`Reactor` or :mat:func:`Reservoir` +% :return: +% Instance of class :mat:func:`FlowDevice` % + m = FlowDevice(1); if nargin == 2 install(m, upstream, downstream) diff --git a/interfaces/matlab/toolbox/Methane.m b/interfaces/matlab/toolbox/Methane.m index 620ce3d18..1ead50741 100644 --- a/interfaces/matlab/toolbox/Methane.m +++ b/interfaces/matlab/toolbox/Methane.m @@ -1,11 +1,17 @@ function m = Methane() -% METHANE - Return an object representing methane. +% METHANE Return an object representing methane. +% m = Methane() +% The object returned by this method implements an accurate equation of +% state for methane that can be used in the liquid, vapor, saturated +% liquid/vapor, and supercritical regions of the phase diagram. The +% equation of state is taken from % -% The object returned by this method implements an accurate equation of -% state for methane that can be used in the liquid, vapor, saturated -% liquid/vapor, and supercritical regions of the phase diagram. The -% equation of state is taken from W. C. Reynolds, "Thermodynamic -% Properties in SI." +% Reynolds, W. C. *Thermodynamic Properties in SI: graphs, tables, and +% computational equations for forty substances* Stanford: Stanford +% University, 1979. Print. +% +% :return: +% Instance of class :mat:func:`Solution` % m = Solution('liquidvapor.cti', 'methane'); diff --git a/interfaces/matlab/toolbox/Nitrogen.m b/interfaces/matlab/toolbox/Nitrogen.m index bb49e75d5..cb3a92fd7 100644 --- a/interfaces/matlab/toolbox/Nitrogen.m +++ b/interfaces/matlab/toolbox/Nitrogen.m @@ -1,11 +1,17 @@ function n = Nitrogen() -% NITROGEN - Return an object representing nitrogen. +% NITROGEN Return an object representing nitrogen. +% n = Nitrogen() +% The object returned by this method implements an accurate equation of +% state for nitrogen that can be used in the liquid, vapor, saturated +% liquid/vapor, and supercritical regions of the phase diagram. The +% equation of state is taken from % -% The object returned by this method implements an accurate equation of -% state for nitrogen that can be used in the liquid, vapor, saturated -% liquid/vapor, and supercritical regions of the phase diagram. The -% equation of state is taken from W. C. Reynolds, "Thermodynamic -% Properties in SI." +% Reynolds, W. C. *Thermodynamic Properties in SI: graphs, tables, and +% computational equations for forty substances* Stanford: Stanford +% University, 1979. Print. +% +% :return: +% Instance of class :mat:func:`Solution` % n = Solution('liquidvapor.cti', 'nitrogen'); diff --git a/interfaces/matlab/toolbox/Oxygen.m b/interfaces/matlab/toolbox/Oxygen.m index 26921241c..2c84d1648 100644 --- a/interfaces/matlab/toolbox/Oxygen.m +++ b/interfaces/matlab/toolbox/Oxygen.m @@ -1,11 +1,17 @@ function o = Oxygen() -% OXYGEN - Return an object representing oxygen. +% OXYGEN Return an object representing oxygen. +% o = Oxygen() +% The object returned by this method implements an accurate equation of +% state for oxygen that can be used in the liquid, vapor, saturated +% liquid/vapor, and supercritical regions of the phase diagram. The +% equation of state is taken from % -% The object returned by this method implements an accurate equation of -% state for oxygen that can be used in the liquid, vapor, saturated -% liquid/vapor, and supercritical regions of the phase diagram. The -% equation of state is taken from W. C. Reynolds, "Thermodynamic -% Properties in SI." +% Reynolds, W. C. *Thermodynamic Properties in SI: graphs, tables, and +% computational equations for forty substances* Stanford: Stanford +% University, 1979. Print. +% +% :return: +% Instance of class :mat:func:`Solution` % o = Solution('liquidvapor.cti', 'oxygen'); diff --git a/interfaces/matlab/toolbox/Reservoir.m b/interfaces/matlab/toolbox/Reservoir.m index e04998487..6f75162bc 100644 --- a/interfaces/matlab/toolbox/Reservoir.m +++ b/interfaces/matlab/toolbox/Reservoir.m @@ -1,20 +1,29 @@ function r = Reservoir(contents) -% RESERVOIR - Create a Reservoir object. +% RESERVOIR Create a Reservoir object. +% r = Reservoir(contents) +% A :mat:func:`Reservoir` is an instance of class :mat:func:`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: % -% 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. +% .. code-block:: matlab % -% r1 = Reservoir % an empty reservoir -% r2 = Reservoir(gas) % a reservoir containing a gas +% r1 = Reservoir % an empty reservoir +% r2 = Reservoir(gas) % a reservoir containing a gas % -% See also: Reactor +% See also: :mat:func:`Reactor` % +% :param contents: +% Cantera :mat:func:`Solution` to be set as the contents of the +% reactor +% :return: +% Instance of class :mat:func:`Reactor` +% + if nargin == 0 contents = 0; end diff --git a/interfaces/matlab/toolbox/Valve.m b/interfaces/matlab/toolbox/Valve.m index 4b98e4d47..b330c0096 100644 --- a/interfaces/matlab/toolbox/Valve.m +++ b/interfaces/matlab/toolbox/Valve.m @@ -1,30 +1,33 @@ function v = Valve(upstream, downstream) +% VALVE Create a valve. +% v = Valve(upstream, downstream) +% Create an instance of class :mat:func:`FlowDevice` configured to +% simulate a valve that produces a flow rate proportional to the +% pressure difference between the upstream and downstream reactors. % -% VALVE - Create a valve connecting two reactors / reservoirs. +% The mass flow rate [kg/s] is computed from the expression % -% m = Valve(upstream, downstream) +% .. math:: \dot{m} = K(P_{upstream} - P_{downstream}) % -% creates an instance of class FlowDevice configured to simulate a -% valve that produces a flow rate proportional to the pressure -% difference between the uupstream and downstream reactors. If two reactor -% objects are supplied as arguments, the valve is installed -% between the two reactors. +% as long as this produces a positive value. If this expression is +% negative, zero is returned. Therefore, the :mat:func:`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. % -% The mass flow rate [kg/s] is computed from the expression +% see also: :mat:func:`FlowDevice`, :mat:func:`MassFlowController` % -% mdot = K ( P_upstream - P_downstream ) +% :param upstream: +% Upstream reactor or reservoir +% :param downstream: +% Downstream Reactor or reservoir % -% 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 mass flow rate, no matter how -% large the pressure difference. THIS MAY CHANGE IN A FUTURE -% RELEASE. -% -% see also: FlowDevice, MassFlowController +% :return: +% Instance of class :mat:func:`FlowDevice` % v = FlowDevice(3); diff --git a/interfaces/matlab/toolbox/Water.m b/interfaces/matlab/toolbox/Water.m index 211a5fc04..72d1b6617 100644 --- a/interfaces/matlab/toolbox/Water.m +++ b/interfaces/matlab/toolbox/Water.m @@ -1,14 +1,20 @@ function w = Water() -% WATER - Return an object representing water. +% WATER Return an object representing water. +% w = Water() +% The object returned by this method implements an accurate equation of +% state for water that can be used in the liquid, vapor, saturated +% liquid/vapor, and supercritical regions of the phase diagram. The +% equation of state is taken from % -% The object returned by this method implements an accurate equation of -% state for water that can be used in the liquid, vapor, saturated -% liquid/vapor, and supercritical regions of the phase diagram. The -% equation of state is taken from W. C. Reynolds, "Thermodynamic -% Properties in SI." +% Reynolds, W. C. *Thermodynamic Properties in SI: graphs, tables, and +% computational equations for forty substances.* Stanford: Stanford +% University, 1979. Print. % -% For more details, see classes Cantera::PureFluid and tpx::water in the -% Cantera C++ source code documentation. +% For more details, see classes Cantera::PureFluid and tpx::water in the +% Cantera C++ source code documentation. +% +% :return: +% Instance of class :mat:func:`Solution` % w = Solution('liquidvapor.cti', 'water'); diff --git a/interfaces/matlab/toolbox/adddir.m b/interfaces/matlab/toolbox/adddir.m index 9b064b818..5daee2d57 100755 --- a/interfaces/matlab/toolbox/adddir.m +++ b/interfaces/matlab/toolbox/adddir.m @@ -1,10 +1,11 @@ function adddir(d) -% ADDDIR Add a directory to the Cantera search path. +% ADDDIR Add a directory to the search path. +% adddir(d) +% Adds directory ``d`` to the set of directories where Cantera looks for +% input and data files. % -% adddir('directory') -% -% adds 'directory' to the set of directories where Cantera looks for -% input and data files. +% :param d: +% Path to add to the MATLAB search path. % ctmethods(0, 3, d); diff --git a/interfaces/matlab/toolbox/air.m b/interfaces/matlab/toolbox/air.m index a20e82512..886d84f9b 100755 --- a/interfaces/matlab/toolbox/air.m +++ b/interfaces/matlab/toolbox/air.m @@ -1,8 +1,12 @@ function gas = air -% AIR - create an object representing air. +% AIR Create an object representing air. +% gas = air +% Air is modeled as an ideal gas mixture. The specification is taken +% from file air.cti. Several reactions among oxygen and nitrogen are +% defined. % -% Air is modeled as an ideal gas mixture, and several reactions -% are defined. The specification is taked from file air.xml. +% :return: +% Instance of class :mat:func:`Solution` % gas = Solution('air.cti', 'air'); diff --git a/interfaces/matlab/toolbox/ck2cti.m b/interfaces/matlab/toolbox/ck2cti.m index 41b33b740..e109def6c 100644 --- a/interfaces/matlab/toolbox/ck2cti.m +++ b/interfaces/matlab/toolbox/ck2cti.m @@ -1,18 +1,30 @@ function f = ck2cti(infile, thermo, transport) -% CK2CTI - Convert a Chemkin-compatible reaction mechanism file to -% Cantera format. +% CK2CTI Convert a CHEMKIN input file to Cantera format. +% f = ck2cti(infile, thermo, transport) +% Examples:: % -% f = ck2cti('chem.inp') -% f = ck2cti('chem.inp', 'therm.dat') -% f = ck2cti('chem.inp', 'therm.dat', 'tran.dat') +% f = ck2cti('chem.inp') +% f = ck2cti('chem.inp', 'therm.dat') +% f = ck2cti('chem.inp', 'therm.dat', 'tran.dat') +% +% These 3 statements all create a Cantera input file 'chem.cti.' In +% the first case, the CK-format file contains all required species +% thermo data, while in the second case some or all thermo data is +% read from file 'therm.dat.' In the third form, the input file +% created will also contain transport property parameters. The +% function return value is a string containing the output file +% name. +% +% :param infile: +% Chemistry input file in CHEMKIN format. Required. +% :param thermo: +% Thermodynamic input file in CHEMKIN format. Optional if +% thermodynamic data is specified in the chemistry input file. +% :param transport: +% Transport input file in CHEMKIN format. Optional. +% :return: +% String with CTML output filename. % -% These 3 statements all create a Cantera input file 'chem.cti.' In -% the first case, the CK-format file contains all required species -% thermo data, while in the second case some or all thermo data is -% read from file 'therm.dat.' In the third form, the input file -% created will also contain transport property parameters. The -% function return value is a string containing the output file -% name. if nargin == 0 error('input file name must be supplied') diff --git a/interfaces/matlab/toolbox/cleanup.m b/interfaces/matlab/toolbox/cleanup.m index 306b00b9a..917233f24 100644 --- a/interfaces/matlab/toolbox/cleanup.m +++ b/interfaces/matlab/toolbox/cleanup.m @@ -1,5 +1,6 @@ function cleanup() -% CLEANUP - Delete all stored Cantera objects and reclaim memory +% CLEANUP Delete all stored Cantera objects and reclaim memory. +% cleanup() % ctmethods(0, 4); diff --git a/interfaces/matlab/toolbox/constants.m b/interfaces/matlab/toolbox/constants.m index f572e20e5..91b832fcb 100755 --- a/interfaces/matlab/toolbox/constants.m +++ b/interfaces/matlab/toolbox/constants.m @@ -1,4 +1,12 @@ function [atm, r] = constants +% CONSTANTS Get the values of important constants. +% [atm,r] = constants +% :return: +% If one output argument is given, returns one atmosphere in +% Pascals. If two output arguments are given, returns one +% atmosphere in Pascals and the universal gas constant in +% J/kmol-K. +% atm = 101325.0; r = 8314.4621; diff --git a/interfaces/matlab/toolbox/gasconstant.m b/interfaces/matlab/toolbox/gasconstant.m index ed5c9a294..9b98c185b 100755 --- a/interfaces/matlab/toolbox/gasconstant.m +++ b/interfaces/matlab/toolbox/gasconstant.m @@ -1,3 +1,8 @@ function r = gasconstant -% GASCONSTANT The universal gas constant in J/kmol-K. +% GASCONSTANT Get the universal gas constant in J/kmol-K. +% r = gasconstant +% :return: +% The universal gas constant in J/kmol-K. +% + r = 8314.4621; diff --git a/interfaces/matlab/toolbox/gaussian.m b/interfaces/matlab/toolbox/gaussian.m index 47591460f..2d1395ede 100644 --- a/interfaces/matlab/toolbox/gaussian.m +++ b/interfaces/matlab/toolbox/gaussian.m @@ -1,13 +1,14 @@ function g = gaussian(peak, center, width) +% GAUSSIAN Create a Gaussian :mat:func:`Func` instance. +% g = gaussian(peak, center, width) +% :param peak: +% The peak value +% :param center: +% Value of x at which the peak is located +% :param width: +% Full width at half-maximum. The value of the +% function at center +/- (width)/2 is one-half +% the peak value. % -% GAUSSIAN - create a Gaussian Func instance -% -% gaussian(peak, center, width) -% -% 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. -% + g = Func('gaussian', 0, [peak, center, width]); diff --git a/interfaces/matlab/toolbox/geterr.m b/interfaces/matlab/toolbox/geterr.m index a530daffd..aa12eaa35 100755 --- a/interfaces/matlab/toolbox/geterr.m +++ b/interfaces/matlab/toolbox/geterr.m @@ -1,4 +1,8 @@ function e = geterr +% GETERR Get the error message from a Cantera error. +% e = geterr +% + try e = ctmethods(0,2); % getCanteraError; catch ME diff --git a/interfaces/matlab/toolbox/importEdge.m b/interfaces/matlab/toolbox/importEdge.m index 2133bccc2..08da014ef 100644 --- a/interfaces/matlab/toolbox/importEdge.m +++ b/interfaces/matlab/toolbox/importEdge.m @@ -1,6 +1,24 @@ function s = importEdge(file, name, phase1, phase2, phase3, phase4) -% IMPORTINTERFACE - import an interface +% IMPORTEDGE Import edges between phases. +% s = importEdge(file, name, phase1, phase2, phase3, phase4) +% Supports up to four neighbor phases. See :ref:`sec-interfaces` % +% :param file: +% File containing phases +% :param name: +% Name of phase +% :param phase1: +% First neighbor phase +% :param phase2: +% Second neighbor phase +% :param phase3: +% Third neighbor phase +% :param phase4: +% Fourth neighbor phase +% :return: +% Instance of class :mat:func:`Interface` +% + if nargin == 3 s = Interface(file, name, phase1); elseif nargin == 4 diff --git a/interfaces/matlab/toolbox/importInterface.m b/interfaces/matlab/toolbox/importInterface.m index 922317757..3ae973b75 100644 --- a/interfaces/matlab/toolbox/importInterface.m +++ b/interfaces/matlab/toolbox/importInterface.m @@ -1,6 +1,20 @@ function s = importInterface(file, name, phase1, phase2) -% IMPORTINTERFACE - import an interface +% IMPORTINTERFACE Import an interface between phases. +% s = importInterface(file, name, phase1, phase2) +% See :ref:`sec-interfaces`. % +% :param file: +% CTI or CTML file containing the interface +% :param name: +% Name of the interface to import +% :param phase1: +% First phase in the interface +% :param phase2: +% Second phase in the interface +% :return: +% Instance of class :mat:func:`Interface` +% + if nargin == 3 s = Interface(file, name, phase1); elseif nargin == 4 diff --git a/interfaces/matlab/toolbox/importPhase.m b/interfaces/matlab/toolbox/importPhase.m index 2fc168956..c3456c904 100644 --- a/interfaces/matlab/toolbox/importPhase.m +++ b/interfaces/matlab/toolbox/importPhase.m @@ -1,6 +1,18 @@ function s = importPhase(file, name) -% IMPORTPHASE - import a phase from a CTI file +% IMPORTPHASE Import a phase from a CTI file +% s = importPhase(file, name) +% See :ref:`sec-phases`. % +% See also: :mat:func:`Solution` +% +% :param file: +% CTI file containing phase definition +% :param name: +% Name of the phase +% :return: +% Instance of class :mat:func:`Solution` +% + if nargin == 1 s = Solution(file); elseif nargin == 2 diff --git a/interfaces/matlab/toolbox/oneatm.m b/interfaces/matlab/toolbox/oneatm.m index 548b4db34..be9aef938 100755 --- a/interfaces/matlab/toolbox/oneatm.m +++ b/interfaces/matlab/toolbox/oneatm.m @@ -1,3 +1,8 @@ function p = oneatm -% ONEATM One atmosphere in Pascals. +% ONEATM Get one atmosphere in Pa. +% p = oneatm +% :return: +% One atmosphere in Pascals. +% + p = 101325.0; diff --git a/interfaces/matlab/toolbox/polynom.m b/interfaces/matlab/toolbox/polynom.m index 10f19c74f..e7b40b47e 100644 --- a/interfaces/matlab/toolbox/polynom.m +++ b/interfaces/matlab/toolbox/polynom.m @@ -1,13 +1,20 @@ function poly = polynom(coeffs) +% POLYNOM Create a polynomial :mat:func:`Func` instance. +% poly = polynom(coeffs) +% The polynomial coefficients are specified by a vector +% ``[a0 a1 .... aN]``. Examples: % -% POLY - create an instance of class 'Func' representing a polynomial. +% .. code-block:: matlab % -% The polynomial coefficients are specified by a one-dimensional -% array [a0 a1 .... aN]. +% polynom([-2 6 3]) %3x^2 + 6.0x - 2 +% polynom([1.0 -2.5 0 0 2]) %2x^4 - 2.5x + 1 % -% polynom([-2 6 3]) 3x^2 + 6x - 2 -% polynom([1.0 -2.5 0 0 2]) 2x^4 - 2.5x + 1 +% :param coeffs: +% Vector of polynomial coefficients +% :return: +% Instance of class :mat:func:`Func` % + [n m] = size(coeffs); if n == 1 poly = Func('polynomial',m - 1,coeffs);