Theory
This chapter answers why this is the right calculation, and its pages are meant to be readable without running anything. The Tutorials drive one feature at a time and the Applications work a real case end to end; here the question is what the equations are, where they come from, and where they stop being true.
What belongs on a theory page, and what does not
These pages carry the general theory: definitions, derivations, and the meaning of each term. Code appears only where the correspondence between a formula and its implementation is the point — a signature, a one-line expression. A theory page does not build a chemical system, does not solve, and does not print a table of numbers; that is what the Applications are for, and every quantitative claim made here is measured there or asserted in the test suite. The division exists so that there is one place to look for each kind of thing.
The symbols
Every symbol of these pages is in the Nomenclature, with its unit, and with the value the package computes with for a physical constant. Hovering an equation shows the symbols it holds, with their meaning on the page.
The three layers, and what each one assumes
ChemistryLab computes in three layers, and almost every surprise comes from a layer's assumptions being carried into a regime it was not built for.
| layer | what it computes | what it assumes |
|---|---|---|
| chemical description | formulas, species, reactions, the conservation matrix | nothing physical — this is bookkeeping, and it is exact |
| equilibrium | a composition satisfying mass-action and phase conditions; a global Gibbs minimum for a consistent convex potential | prescribed temperature and pressure by default, well-mixed declared phases, ideal molar volumes, and an activity model |
| kinetics | a trajectory in time, optionally re-equilibrating the solution at every step | a rate law per reaction, and that the rate law's arguments are available |
The three layers organize the calculation. Each layer adds assumptions to the chemical bookkeeping; kinetic calculations can optionally re-equilibrate the solution as the reaction progresses.
The activity model is where the second layer stops being ideal, so it is the first thing to read and the first thing to suspect: Activity models.
Reading order
The chapter can be read in two ways, and the first is short.
A first reading
These pages answer, in order, the questions a reader new to thermodynamics asks about what the package computes on a cement. Each opens with the questions it answers.
The two laws, and what the Gibbs energy measures rebuilds the enthalpy a calorimeter measures and the Gibbs energy the solver minimizes, and says what each is not:
and are not two flows of heat, and a kinetic history is not a state function. The chemical potential and reactions lets the composition change: the chemical potential, why the activity of water is tied to those of the solutes, the Gibbs energy of a reaction as a slope, the equilibrium constant, and why a metastable state is not a local minimum of
. Activity models, §1 to §3: where the activity of an ion comes from, and why the water activity cannot be chosen separately.
The water budget of a hydrating paste: what a Gibbs minimization predicts about a hydrating paste, and what it cannot.
For further reading, and for reference
Formation quantities and the database completes the foundations with what a database stores: energies of formation, absolute and conventional entropies, how these are measured, and how a standard potential is carried to any temperature and pressure, up to the apparent Gibbs energy the package reads. Thermochemistry follows, since it fixes the notation of the whole chapter, which is that of the code, and Standard states completes it by stating what each activity is measured from. Proving that an answer is the answer then explains why an equilibrium computed here can be checked rather than trusted: the optimality conditions can be audited on any composition, they are sufficient for a global minimum when the activities derive from one convex energy, and the certificate says whether they do. The same page fixes the meaning of stable, metastable and partial equilibrium, on which the kinetic chapters rely.
The places where a mixture stops being ideal follow. Activity models treats the aqueous phase, on which every equilibrium depends whether or not it is mentioned, and Solid solutions a solid of variable composition. Oxidation state adds the conserved quantity that is not an element, together with the potential conjugate to it, which no binder containing slag can do without, and Chemistry that happens on a surface uses both preceding ideas, a site balance being written like the charge row and site mixing like a solid solution. Rate laws leaves equilibrium for time and gives the provenance of every parameter entering a rate, and Kinetics under partial equilibrium joins the two: the partition between the slow reactions and the fast ones, the differential system with its exact Jacobian, the implicit step, and the energy balance of a calorimeter.
The water budget of a hydrating paste is the cement-specific chapter, and the one to read if the question is why a calculation predicts a threshold at
The constraint machinery — what can be held fixed instead of