===========================
Objects Representing Phases
===========================

Solution
--------

.. mat:class:: Solution(src, id, trans)

    Solution class constructor.

    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. ::
    
        >> s = Solution('input.xml'[, phase_name[, transport_model]])
    
    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 :mat:func:`Solution` derives from three more basic classes, and most of
    its methods are inherited from these classes. These are:
    
        * 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`
    

    .. mat:function:: Air()

        Create an object representing air.

        Air is modeled as an ideal gas mixture. The specification is taken
        from file ``air.xml``. Several reactions among oxygen and nitrogen are
        defined.
        
        :return:
            Instance of class :mat:func:`Solution`
        

    .. mat:function:: GRI30(tr)

        Create an object with the GRI-Mech 3.0 reaction mechanism.

        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 available from http://www.me.berkeley.edu/gri_mech/
        
        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`
        

    .. mat:function:: IdealGasMix(infile, b, c)

        Create a mixture of ideal gases.

        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']]])
        
        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')
            g2 = IdealGasMix('mech2.inp')
            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.
        
        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: :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`
        

Mixture
-------

.. mat:class:: Mixture(phases)

    Multiphase mixture class constructor.

    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::
    
        >> gas = Solution('gas.cti');
        >> graphite = Solution('graphite.cti');
        >> mix = Mixture({gas, 1.0; graphite, 0.1});
    
    Phases may also be added later using the addPhase method::
    
        >> water = Solution('water.cti');
        >> addPhase(mix, water, 3.0);
    
    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`
    

    .. mat:function:: addPhase(self, phase, moles)

        Add a phase to a mixture.

        :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
        

    .. mat:function:: chemPotentials(self)

        Get the chemical potentials of species in a mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :return:
            Vector of chemical potentials. Units: J/kmol
        

    .. mat:function:: elementIndex(self, name)

        Get the index of an element.

        :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``
        

    .. mat:function:: equilibrate(self, XY, err, maxsteps, maxiter, loglevel)

        Set the mixture to a state of chemical equilibrium.

        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.
        
        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. ::
        
            >> 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
        

    .. mat:function:: nElements(self)

        Get the number of elements in a mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :return:
            Number of elements in the input
        

    .. mat:function:: nPhases(self)

        Get the number of phases in a mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :return:
            Number of phases in the input
        

    .. mat:function:: nSpecies(self)

        Get the number of species in a mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :return:
            Number of species in the input
        

    .. mat:function:: phaseMoles(self, n)

        Get the number of moles of a phase in a mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :param n:
            Integer phase number in the input
        :return:
            Moles of phase number ``n``. Units: kmol
        

    .. mat:function:: pressure(self)

        Get the pressure of the mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :return:
            Pressure. Units: Pa
        

    .. mat:function:: setPhaseMoles(self, n, moles)

        Set the number of moles of a phase in a mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :param n:
            Phase number in the input
        :param moles:
            Number of moles to add. Units: kmol
        

    .. mat:function:: setPressure(self, P)

        Set the pressure of the mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :param P:
            Pressure. Units: Pa
        

    .. mat:function:: setSpeciesMoles(self, moles)

        Set the moles of the species.

        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. ::
        
            >> 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
        

    .. mat:function:: setTemperature(self, T)

        Set the mixture temperature.

        :param self:
            Instance of class :mat:func:`Mixture`
        :param T:
            Temperature. Units: K
        

    .. mat:function:: speciesIndex(self, k, p)

        Get the index of a species in a mixture.

        :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``
        

    .. mat:function:: temperature(self)

        Get the temperature of a mixture.

        :param self:
            Instance of class :mat:func:`Mixture`
        :return:
            Temperature (K)
        

Interface
---------

.. mat:class:: Interface(src, id, p1, p2, p3, p4)

    Interface class constructor.

    See `Interfaces <https://cantera.org/tutorials/cti/phases.html#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`
    

    .. mat:function:: concentrations(s)

        Get the concentrations of the species on an interface.

        :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.
        

    .. mat:function:: coverages(s)

        Get the surface coverages of the species on an interface.

        :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.
        

    .. mat:function:: importEdge(file, name, phase1, phase2, phase3, phase4)

        Import edges between phases.

        Supports up to four neighbor phases. See
        `Interfaces <https://cantera.org/tutorials/cti/phases.html#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`
        

    .. mat:function:: importInterface(file, name, phase1, phase2)

        Import an interface between phases.

        See `Interfaces <https://cantera.org/tutorials/cti/phases.html#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`
        

    .. mat:function:: setCoverages(s, cov, norm)

        Set surface coverages of the species on an interface.

        :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'``
        :param norm:
             Optional flag that denotes whether or not to normalize the species
             coverages. ``norm`` is either of the two strings ``'nonorm'``` or
             ``'norm'``. If left unset, the default is `norm`. This only works if
             ``s`` is a vector, not a string. Since unnormalized coverages can lead to
             unphysical results, ``'nonorm'`` should be used only in rare cases, such
             as computing partial derivatives with respect to a species coverage.
        

Pure Fluid Phases
-----------------

    .. mat:function:: CarbonDioxide()

        Return an object representing carbon dioxide.

        The object returned by this method implements an accurate equation of
        state for carbon dioxide 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
        
        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::CarbonDioxide in the
        Cantera C++ source code documentation.
        
        :return:
            Instance of class :mat:func:`Solution`
        

    .. mat:function:: HFC134a()

        Return an object representing refrigerant HFC134a.

        The object returned by this method implements an accurate equation of
        state for refrigerant HFC134a (R134a)  that can be used in the liquid,
        vapor, saturated liquid/vapor, and supercritical regions of the phase
        diagram. Implements the equation of state given in:
        R. Tillner-Roth and H.D. Baehr. "An International Standard Formulation for
        The Thermodynamic Properties of 1,1,1,2-Tetrafluoroethane (HFC-134a) for
        Temperatures From 170 K to 455 K and Pressures up to 70 MPa". J. Phys.
        Chem. Ref. Data, Vol. 23, No. 5, 1994. pp. 657--729.
        http://dx.doi.org/10.1063/1.555958
        
        For more details, see classes Cantera::PureFluid and tpx::HFC134a in the
        Cantera C++ source code documentation.
        
        :return:
            Instance of class :mat:func:`Solution`
        

    .. mat:function:: Hydrogen()

        Return an object representing 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
        
        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.
        
        :return:
            Instance of class :mat:func:`Solution`
        

    .. mat:function:: Methane()

        Return an object representing 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
        
        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`
        

    .. mat:function:: Nitrogen()

        Return an object representing 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
        
        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`
        

    .. mat:function:: Oxygen()

        Return an object representing 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
        
        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`
        

    .. mat:function:: Water()

        Return an object representing 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
        
        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.
        
        :return:
            Instance of class :mat:func:`Solution`