The files IGL passes around
Running a model happens in two steps, and each leaves a file behind. This page describes those files.
You do not need any of it to use IGL. You do need it to check what a run actually did, or to write your own engine.
Both files carry their own version number, kept apart from the language. A results file gaining a new field should not force anyone to rewrite a model.
The prepared model, version 1.3
igl build turns your .igl file into a
.iglir.json. It is your model with the reading and checking already
done: names looked up, units converted to a single set, and a record of where
everything came from.
This is the file a calculation engine actually reads. The work is split at this point so that a second engine is possible: whoever writes one starts from this document and never has to open our code.
{
"ir_version": "1.3",
"provenance": {
"source_path": "model.igl",
"source_sha256": "bc8abdb...",
"databases": [
{ "path": "cr_53cr_52cr.igdb",
"resolved": "C:/Program Files/IGL/databases/cr_53cr_52cr.igdb",
"sha256": "d20ee19..." }
],
"generator": "igl 0.1.0"
},
"species": [ ... ], "reservoirs": [ ... ], "processes": [ ... ]
}
Note the two entries for the database. One is what your model asked for, the other is which file actually answered. They can differ. A database named without a path might be the copy next to your model or the one that came with the installation, and recording only the request would leave you unable to tell which you got.
The results, version 1.1
igl run writes a results.json. Each column says what
it holds and in what unit, and each row is one recorded state.
{
"format_version": "1.1",
"engine": { "name": "igl-engine", "version": "0.1.0" },
"model": { "ir_version": "1.3", "source_sha256": "bc8abdb...", "simulation": "Closed" },
"columns": [
{ "name": "Groundwater.Cr(VI).delta53Cr", "kind": "pool_composition",
"unit": "permil", "reservoir": "Groundwater",
"species": "Cr(VI)", "isotope": "53Cr/52Cr" }
],
"rows": [ [0.0], [3.212165544] ],
"diagnostics": [ ],
"backends": [ ]
}
A value that does not exist is written as null, never as zero.
Before a reaction starts there is no product and so no composition to report.
Writing 0 permil there would be a measurement nobody made.
engine names the code that did the arithmetic, not the program you
launched. Run the same model from the command line, from the editor and from a
script, and all three report the same engine. When two results disagree, what
you want to know is which code produced them.
backends is filled in when a chemistry program such as PHREEQC fed
the run. It records which executable ran, which thermodynamic database it used
and that file's fingerprint, and the values that came back.
It is written even when the run failed. If PHREEQC refused to run, knowing which PHREEQC it was is exactly what you need.
Fractionation databases, version 1.1
A database holds standards and fractionation factors, and every value carries the reference it came from. There is no exception to that: an entry without a source cannot go in.
[[fractionation]] ratio = "53Cr/52Cr" process = "reduction" reactant = "Cr(VI)" product = "Cr(III)" regime = "kinetic" context = "natural" epsilon = -3.5 ph_range = [6.5, 8.5] citation = "Basu et al., 2014" doi = "10.1016/..." notation = "epsilon53Cr(III)-Cr(VI)"
When your model asks for a factor, the search matches on the ratio, the process and the two species, then narrows using your stated conditions. An entry whose temperature and pH range cover your model beats one that says nothing about them. Both beat an entry that rules your conditions out.
If two entries end up equally good, the run stops and tells you which studies are involved. That situation usually means two groups measured the same reaction and got different answers. If the engine picked one for you, it would be settling that disagreement without telling you it existed.
notation is there for you, not for the software. It records how the
original paper wrote the quantity, so you can hold the paper next to the entry
and see that they match.
No program reads it. Everything the software needs is already in the fields above, and working out what a number means from a caption would mean guessing at something the fields state plainly.
The published databases can be downloaded.