Improve documentation of 1D (flame) solver

[speth]

Abstract Better documentation of the 1D (flame) solver is needed, in a couple of areas.

Proposed Solution API Documentation: Many member variables and some member functions of classes used in 1D flame simulations are not documented, or are not documented in a way that Doxygen can include them in the generated API documentation. Notably affected classes:

• StFlow
• OneDim
• Bdry1D
• Inlet1D
• ReactingSurf1D

As an implementation note, one case where documentation should not be added are overrides for which the base class's documentation is adequate. Doxygen pages for derived classes automatically shows the base class documentation for such methods.

Solution Method Documentation: While the governing equations are reasonably-well documented on the website, the method of solving these equations is not. The main components are:

• Discretization of the governing equations
• Handling of boundary conditions
• Handling of algebraic constraints
• Grid refinement algorithm
• Hybrid time stepping / steady state solver

This documentation should be added to the "Science" section of the website.

[wandadars]

The toughest part of examining the discretization scheme is trying to understand why some points are evaluated at the midpoints and others are not. Like the continuity equation has the 2rhoV term, which I think doesn't need a stencil, as at point j we have rho(j) and V(j). Yet an average between neighboring V values, upwinded from the right is used.

[speth]

In the case of the continuity equation, I think the point is that you aren't trying to compute an upwinded derivative -- this isn't a transport equation, and the stability concern that motivates upwinding doesn't apply. Instead, since computing $du/dz$ based on points j and j+1 is a centered difference approximation at j+1/2, you want the other term to be an approximation for $2\rho V$ at j+1/2 as well.

[wandadars]

I see. I've been looking over references for finite-difference methods to try and find the point where I can map back what is done in the 1D solver to an established approach. When I look at the continuity equation, I see a one-sided finite-difference approximation of the first derivative applied at the left boundary node, which is why the averaging of the V term seemed strange to me. Some of the things where evaluations are being made at j+1/2 points reminds me finite volume style approximations.

[ischoegl]

Significantly improved (and potentially closed?) via Cantera/cantera#1757 and Cantera/cantera#1759. Kudos to @wandadars!

[speth]

Yes, a big thank you to @wandadars for the progress on this. I'd like to leave this issue open for the time being, as I think there are still a few things mentioned in the lists above that haven't been covered, and that I would like address at some level before the Cantera 3.1 release.