The most important part of adding a model is not choosing a filename. It is satisfying the contract that shared property routines and solvers already expect. A function that returns a plausible pressure at one state can still have incorrect composition derivatives, an incompatible volume initializer, or an energy normalized on the wrong amount basis.
Use this page alongside the repository map. For complete model implementations, continue to the analytical and automatic-differentiation tutorials.
A derived type groups data and procedures. A type can extend a parent and
inherit its data and methods. A deferred binding specifies a procedure
interface but leaves its implementation to a concrete extension. A variable
declared with class(ArModel) can refer to different concrete EOS types.
! Fragment inside a program that imports these names from yaeos.
class(ArModel), allocatable :: model
model = PengRobinson76(tc, pc, omega)
call model%pressure(n, V, T, P)
The assignment constructs a concrete model. The pressure routine then calls
the residual_helmholtz binding associated with that concrete type. You do not
need a select type branch for every EOS in a generic property calculation.
Add one only when the operation genuinely requires model-specific information.
BaseModel contains components, a Substances value whose arrays hold
critical properties and other metadata in component order. A constructor must
initialize the fields its algorithms actually use; leaving arrays unallocated
and hoping every inherited method tolerates that is not a valid contract.
The defining interface is abs_residual_helmholtz in
src/models/residual_helmholtz/ar_models.f90. Its inputs are component mole
amounts n(:), total volume V, and temperature T. Outputs are optional:
| Output | Meaning | Shape |
|---|---|---|
Ar |
Residual Helmholtz energy | Scalar |
ArV, ArT |
First volume and temperature derivatives | Scalar |
ArV2, ArT2, ArTV |
Second state derivatives | Scalar |
Arn |
Mole-number gradient | (nc) |
ArVn, ArTn |
State/mole-number mixed derivatives | (nc) |
Arn2 |
Mole-number Hessian | (nc,nc) |
Here nc = size(n). The derivatives are with respect to amounts, not
independently varied mole fractions. Holding total volume fixed while varying
one amount changes both density and composition. Normalizing n before
differentiating can silently implement a different derivative.
The energy is in bar·L, not automatically J/mol or the reduced molar quantity . If a published correlation supplies a dimensionless molar energy , convert it consistently:
Differentiate the full extensive expression, including its amount and temperature factors. Adding those factors only to the final energy output does not fix derivatives that were taken on a different function.
For fixed temperature, the extensive scaling identity is
It implies, for example, . These identities make useful tests alongside independent derivative checks.
Guard assignment to an optional output with present. Do not reference an
absent output as a temporary. This is a schematic implementation fragment,
not a complete energy kernel:
! Compute local values independently of whether corresponding outputs exist.
if (present(ArV)) ArV = local_ArV
if (present(Arn)) Arn = local_Arn
Also consider what a caller requests internally. The current shared
pressure method requests several state derivatives even when the user asks
only for pressure. Conversely, direct calls can request just a Hessian or a
mixed derivative without requesting Ar. A model must not work only for the
combination used in its first example.
Tests should include energy only, individual derivatives, mixed combinations, and all outputs together. Verify that repeated calls do not depend on uninitialized work arrays or results left by a previous call.
GeModel in src/models/excess_gibbs/ge_models.f90 requires
excess_gibbs(self, n, T, Ge, GeT, GeT2, Gen, GeTn, Gen2). The pattern is
similar, but there is no volume input and no EOS volume root in this contract.
Gen and GeTn are vectors; Gen2 is a matrix.
The shared activity-coefficient method uses
As with Helmholtz energy, an excess-Gibbs implementation must return the
extensive energy on the library’s unit basis. A molar correlation needs its
total-amount factor. Do not route a liquid activity model through an EOS
property calculation merely because both types inherit BaseModel.
| Route | Implement | Good reason to choose it | Main risk to test |
|---|---|---|---|
| Analytical | The real-valued energy and derivative interface | Existing reliable formulas or optimized kernel | Algebra, index orientation, optional branches |
| Hyperdual | The adapter’s hyperdual energy function and required model support | A clear primal expression with overloaded operations | Unsupported operations, dropped derivative lanes, nonsmooth branches |
| Tapenade | Primal routines plus generated derivative bindings | Source-to-source differentiation of a real-valued kernel | Seed/adjoint contracts, generated code integration and reproducibility |
Automatic differentiation applies chain rules to the program you wrote. It does not know whether you implemented the intended thermodynamic equation or used the right units. Keep analytical identities and independent numerical checks in all three routes.
For an existing cubic model, first ask whether a new AlphaFunction or
CubicMixRule is enough. Replacing the entire CubicEoS energy implementation
to change one temperature correlation duplicates more logic than necessary.
An ArModel also implements get_v0(self, n, P, T). The default volume solver
uses it to initialize the dense branch. The specialized Michelsen volume
algorithm uses a covolume or lower-volume scale in a reduced-coordinate solve.
These roles are not identical.
Choose an initializer compatible with the actual volume method your model
uses. An ideal-gas volume returned for every branch is not automatically an
adequate liquid initializer. If a model overrides volume, check that the
override has the inherited signature and consistent root/failure behavior.
Read src/models/solvers/volume.f90 and a comparable model before reusing that
solver. Test pressure recovered at the solved volume, extensive volume
scaling, and both requested root branches at appropriate states.
A new model module normally has three parts: a type that stores its parameters, a constructor that initializes them, and the bound procedures. Keep parameter validation near construction where possible. Document dimensions, units, interaction matrix orientation, and whether inputs are copied.
To publish a model, trace the relevant imports through
src/models/models.f90 and src/yaeos.f90. To publish an equilibrium routine,
also check src/equilibria/equilibria.f90. Use narrow imports inside
implementation modules to reduce unnecessary dependencies and name conflicts.
Adding a use line in the facade is not sufficient for Python support. The
flat wrapper, constructor handle management, Python class, and package exports
are separate changes. Follow the end-to-end checklist.
Use one variable declaration per line so each argument or work value can have an unambiguous description:
real(pr), intent(in) :: T !! Temperature [K].
real(pr), intent(out) :: P !! Pressure [bar].
For modules, types, and procedures, write a title and short summary, then
# Description, # Examples, and # References when references are needed.
Explain why the calculation exists and what a caller must guarantee, not just
the English expansion of its name. Mark schematic fragments as such; avoid
examples with undeclared variables presented as complete programs.
Source comments are part of the implementation’s interface. If a change alters units, failure behavior, shape, default settings, or derivative conventions, update the comments, user guide, and relevant wrapper documentation together.
Before review, be able to answer:
Continue with numerical algorithms if you are changing a solver, or testing to turn these contracts into regression checks.