search

Cantera / enhancements

Repository for proposed and ongoing enhancements to Cantera
11 stars 5 forks source link

Verify, catalog, and document Cantera ThermoPhase classes. #6

Open decaluwe opened 5 years ago

decaluwe commented 5 years ago

Cantera's ThermoPhase class list contains approximately 30-some classes, representing a range of phase-types. However, these classes also represent a range of utility, functionality, and documentation. Some models are improperly or incompletely implemented, some lack coherent documentation, some lack examples required to demonstrate use cases and implementation details, while others lack the test coverage required to maintain functionality with updates to the codebase. Beyond a handful of core models, it is at present difficult for an interested user to understand the functionality, purpose, and implementation details for many of Cantera's available models. Lastly, there are a handful of classes with only marginal utility -- classes that largely duplicate functionality that is already present elsewhere in the thermophase classes or that implement models with either dubious physical validity or limited possible use cases.

Simultaneously, the 'Science' section on Cantera's website provides a logical space to document the scientific theory underpinning Cantera's various classes, but is at present underutilized. This would be a great venue for both cataloging and documenting Cantera's various thermophase classes.

This issue, therefore proposes two/three main tasks:

  1. A thorough review of Cantera's thermophase classes (current as of 15 June, 2019). The review should identify:

    • Overall summary of the model, including general use cases.
    • Identify governing equations for phase (p-v-T) behavior
    • Identify the expressions used for activity concentration, standard concentration, and standard-state chemical potential.

  2. Identify models which can be deprecated. This might be justified by any combination of: poor or incomplete implementation, a lack of documentation or test suite coverage to verify correct functionality, or functionality that is largely duplicated in other thermophase classes. Classes which currently see moderate or heavy usage should not be candidates for deprecation, regardless of any of the above conditions (i.e. we would rather attempt to rectify the deficiencies, in place of deprecating the model).

  3. After completing steps 1 and 2, Move documentation of the thermophase classes to https://cantera.org/science. This should include a brief overview of the available classes, consisting of some subsection of the review in part 1, with links available to a more in-depth documentation of each class (i.e. duplication of the docstrings available in the class's header file).

We will use this space to document progress through this review and documentation.

ischoegl commented 2 years ago

Fwiw, here is an alphabetic list taken from the most recent YAML API docs (Cantera 2.6), which could serve as a starting point (there may be others):