interfaces/clib/include/cantera_clib/ctonedim.h

Go to the documentation of this file.

/**
 *  CTONEDIM - Generated CLib %Cantera interface library.
 *
 *  @file ctonedim.h
 *
 *  Generated CLib API for %Cantera's Sim1D class.
 *
 *  This library of functions is designed to encapsulate %Cantera functionality
 *  and make it available for use in languages and applications other than C++.
 *  A set of library functions is provided that are declared "extern C". All
 *  %Cantera objects are stored and referenced by integers - no pointers are
 *  passed to or from the calling application.
 *
 *  This file was generated by sourcegen. It will be re-generated by the
 *  %Cantera build process. Do not manually edit.
 *
 *  @warning  This library is an experimental part of the %Cantera API and
 *      may be changed without notice.
 */
 
// This file is part of Cantera. See License.txt in the top-level directory or
// at https://cantera.org/license.txt for license and copyright information.
 
#ifndef CTONEDIM_H
#define CTONEDIM_H
 
#include <stdint.h>  // for 32-bit int32_t / 64-bit int64_t
 
#ifdef __cplusplus
extern "C" {
#endif
 
    /**
     *  @defgroup CAPIctonedim ctonedim Library
     *  Generated CLib API for %Cantera's Sim1D class.
     *
     *  @warning  This library is an experimental part of the %Cantera API and
     *      may be changed or removed without notice.
     *
     *  @ingroup CAPIindex
     */
 
    /**
     *  @addtogroup CAPIctonedim
     *  @{
     */
 
    /**
     *  Create a Sim1D object with a list of domains.
     *
     *  Wraps C++ constructor: `shared_ptr<Sim1D> newSim1D(vector<shared_ptr<Domain1D>>&)`
     *
     *  Uses:
     *  - `Domain1D& OneDim::domain(size_t)`
     *
     *  @param[in] domainsLen Length of array reserved for domains.
     *  @param domains      Memory holding Domain1D objects. A vector of shared pointers to the domains to be linked together. The domain pointers must be entered in left-to-right order
     *  @returns            Handle to stored Sim1D object or -1 for exception handling.
     */
    int32_t sim1D_newSim1D(int32_t domainsLen, int32_t* domains);
 
    /**
     *  Set a single value in the solution vector.
     *
     *  Wraps C++ method: `void Sim1D::setValue(size_t, size_t, size_t, double)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param dom          domain number, beginning with 0 for the leftmost domain.
     *  @param comp         component number
     *  @param localPoint   grid point within the domain, beginning with 0 for the leftmost grid point in the domain.
     *  @param value        the value.
     *
     *  @deprecated Per C++ annotation: To be removed after Cantera 3.2. Replaceable by Domain1D::setValue()
     */
    int32_t sim1D_setValue(int32_t handle, int32_t dom, int32_t comp, int32_t localPoint, double value);
 
    /**
     *  Specify a profile for one component of one domain.
     *
     *  Wraps C++ method: `void Sim1D::setProfile(size_t, size_t, const vector<double>&, const vector<double>&)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param dom          Undocumented.
     *  @param comp         Undocumented.
     *  @param[in] posLen   Length of vector reserved for pos.
     *  @param pos          Undocumented.
     *  @param[in] valuesLen Length of vector reserved for values.
     *  @param values       Undocumented.
     *
     *  @deprecated Per C++ annotation: To be removed after Cantera 3.2. Replaceable by Domain1D::setProfile.
     */
    int32_t sim1D_setProfile(int32_t handle, int32_t dom, int32_t comp, int32_t posLen, const double* pos, int32_t valuesLen, const double* values);
 
    /**
     *  Set component 'comp' of domain 'dom' to value 'v' at all points.
     *
     *  Wraps C++ method: `void Sim1D::setFlatProfile(size_t, size_t, double)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param dom          Undocumented.
     *  @param comp         Undocumented.
     *  @param v            Undocumented.
     *
     *  @deprecated Per C++ annotation: To be removed after Cantera 3.2. Replaceable by Domain1D::setProfile.
     */
    int32_t sim1D_setFlatProfile(int32_t handle, int32_t dom, int32_t comp, double v);
 
    /**
     *  Set initial guess for one component for all domains.
     *
     *  Wraps C++ method: `void Sim1D::setInitialGuess(const string&, vector<double>&, vector<double>&)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param component    component name
     *  @param[in] locsLen  Length of vector reserved for locs.
     *  @param[in] locs     A vector of relative positions, beginning with 0.0 at the left of the domain, and ending with 1.0 at the right of the domain.
     *  @param[in] valsLen  Length of vector reserved for vals.
     *  @param[in] vals     A vector of values corresponding to the relative position locations.
     *
     *  @deprecated Per C++ annotation: To be removed after Cantera 3.2. Replaceable by Domain1D::setProfile.
     */
    int32_t sim1D_setInitialGuess(int32_t handle, const char* component, int32_t locsLen, double* locs, int32_t valsLen, double* vals);
 
    /**
     *  Show logging information on current solution for all domains.
     *
     *  Wraps C++ method: `void Sim1D::show()`
     *
     *  @param handle       Handle to queried Sim1D object.
     */
    int32_t sim1D_show(int32_t handle);
 
    /**
     *  Set the number of time steps to try when the steady Newton solver is unsuccessful.
     *
     *  Wraps C++ method: `void SteadyStateSystem::setTimeStep(double, const vector<int>&)`
     *
     *  @param handle       Handle to queried SteadyStateSystem object.
     *  @param stepSize     Initial time step size [s]
     *  @param[in] tStepsLen Length of vector reserved for tSteps.
     *  @param tSteps       A sequence of time step counts to take after subsequent failures of the steady-state solver. The last value in `tsteps` will be used again after further unsuccessful solution attempts.
     */
    int32_t sim1D_setTimeStep(int32_t handle, double stepSize, int32_t tStepsLen, const int32_t* tSteps);
 
    /**
     *  Get the initial value of the system state from each domain in the simulation.
     *
     *  Wraps C++ method: `void Sim1D::getInitialSoln()`
     *
     *  @param handle       Handle to queried Sim1D object.
     */
    int32_t sim1D_getInitialSoln(int32_t handle);
 
    /**
     *  Performs the hybrid Newton steady/time-stepping solution.
     *
     *  Wraps C++ method: `void Sim1D::solve(int, bool)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param loglevel     Controls the amount of diagnostic output.
     *  @param refine_grid  If `true`, the grid will be refined
     */
    int32_t sim1D_solve(int32_t handle, int32_t loglevel, int32_t refine_grid);
 
    /**
     *  Refine the grid in all domains.
     *
     *  Wraps C++ method: `int Sim1D::refine(int)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param loglevel     Undocumented.
     */
    int32_t sim1D_refine(int32_t handle, int32_t loglevel);
 
    /**
     *  Set grid refinement criteria.
     *
     *  Wraps C++ method: `void Sim1D::setRefineCriteria(int, double, double, double, double)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param dom          Undocumented.
     *  @param ratio        Undocumented.
     *  @param slope        Undocumented.
     *  @param curve        Undocumented.
     *  @param prune        Undocumented.
     */
    int32_t sim1D_setRefineCriteria(int32_t handle, int32_t dom, double ratio, double slope, double curve, double prune);
 
    /**
     *  Set the minimum grid spacing in the specified domain(s).
     *
     *  Wraps C++ method: `void Sim1D::setGridMin(int, double)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param dom          Domain index. If dom == -1, the specified spacing is applied to all domains.
     *  @param gridmin      The minimum allowable grid spacing [m]
     */
    int32_t sim1D_setGridMin(int32_t handle, int32_t dom, double gridmin);
 
    /**
     *  Save current simulation data to a container file or CSV format.
     *
     *  Wraps C++ method: `void Sim1D::save(const string&, const string&, const string&, bool)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param fname        Name of output file (CSV, YAML or HDF)
     *  @param name         Identifier of storage location within the container file; this node/group contains header information and multiple subgroups holding domain-specific SolutionArray data (YAML/HDF only)
     *  @param desc         Custom comment describing the dataset to be stored (YAML/HDF only)
     *  @param overwrite    Force overwrite if file/name exists; optional (default=false)
     */
    int32_t sim1D_save(int32_t handle, const char* fname, const char* name, const char* desc, int32_t overwrite);
 
    /**
     *  Retrieve data from a previously saved simulation.
     *
     *  Wraps C++ method: `void Sim1D::_restore(const string&, const string&)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param fname        Name of container file (YAML or HDF)
     *  @param name         Identifier of location within the container file; this node/group contains header information and subgroups with domain-specific SolutionArray data
     */
    int32_t sim1D_restore(int32_t handle, const char* fname, const char* name);
 
    /**
     *  Write statistics about the number of iterations and Jacobians at each grid level.
     *
     *  Wraps C++ setter: `void OneDim::writeStats(int)`
     *
     *  @param handle       Handle to queried OneDim object.
     *  @param printTime    Boolean that indicates whether time should be printed out The default is true. It's turned off for test problems where we don't want to print any times
     */
    int32_t sim1D_writeStats(int32_t handle, int32_t printTime);
 
    /**
     *  Get the index of the domain named `name`.
     *
     *  Wraps C++ method: `size_t OneDim::domainIndex(const string&)`
     *
     *  @param handle       Handle to queried OneDim object.
     *  @param name         Undocumented.
     */
    int32_t sim1D_domainIndex(int32_t handle, const char* name);
 
    /**
     *  Get one entry in the solution vector.
     *
     *  Wraps C++ method: `double Sim1D::value(size_t, size_t, size_t)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param dom          domain number, beginning with 0 for the leftmost domain.
     *  @param comp         component number
     *  @param localPoint   grid point within the domain, beginning with 0 for the leftmost grid point in the domain.
     *
     *  @deprecated Per C++ annotation: To be removed after Cantera 3.2. Replaceable by Domain1D::value()
     */
    double sim1D_value(int32_t handle, int32_t dom, int32_t comp, int32_t localPoint);
 
    /**
     *  Get an entry in the work vector, which may contain either a new system state or the current residual of the system.
     *
     *  Wraps C++ method: `double Sim1D::workValue(size_t, size_t, size_t)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param dom          domain index
     *  @param comp         component index
     *  @param localPoint   grid point within the domain
     *
     *  @deprecated Per C++ annotation: To be removed after Cantera 3.2. Replaceable by Domain1D::getResiduals()
     */
    double sim1D_workValue(int32_t handle, int32_t dom, int32_t comp, int32_t localPoint);
 
    /**
     *  Evaluate the residual function.
     *
     *  Wraps C++ method: `void Sim1D::eval(double*, double*, double, int)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param[in] xLen     Length of array reserved for x.
     *  @param[in] x        State vector
     *  @param[in] rLen     Length of array reserved for r.
     *  @param[out] r       On return, contains the residual vector
     *  @param rdt          Reciprocal of the time step. if omitted, then the internally stored value (accessible using the rdt() method) is used.
     *  @param count        Set to zero to omit this call from the statistics
     */
    int32_t sim1D_eval(int32_t handle, int32_t xLen, double* x, int32_t rLen, double* r, double rdt, int32_t count);
 
    /**
     *  Set the maximum number of steps that can be taken using the same Jacobian before it must be re-evaluated.
     *
     *  Wraps C++ method: `void SteadyStateSystem::setJacAge(int, int)`
     *
     *  @param handle       Handle to queried SteadyStateSystem object.
     *  @param ss_age       Age limit during steady-state mode
     *  @param ts_age       Age limit during time stepping mode. If not specified, the steady-state age is also used during time stepping.
     */
    int32_t sim1D_setMaxJacAge(int32_t handle, int32_t ss_age, int32_t ts_age);
 
    /**
     *  Add node for fixed temperature point of freely propagating flame.
     *
     *  Wraps C++ method: `int Sim1D::setFixedTemperature(double)`
     *
     *  @param handle       Handle to queried Sim1D object.
     *  @param t            Undocumented.
     */
    int32_t sim1D_setFixedTemperature(int32_t handle, double t);
 
    /**
     *  Delete Sim1D object.
     *
     *  Wraps C++ destructor: `undefined`
     *
     *  @param handle       Handle to Sim1D object.
     *  @returns            Zero for success and -1 for exception handling.
     */
    int32_t sim1D_del(int32_t handle);
 
    /**
     *  Return size of Sim1D storage.
     *
     *  Wraps C++ reserved CLib function: `custom code`
     *
     *  @returns            Size or -1 for exception handling.
     */
    int32_t sim1D_cabinetSize();
 
    /**
     *  @}
     */
 
#ifdef __cplusplus
}
#endif
 
#endif // CTONEDIM_H