IGL documentation

01File structure

A model is a UTF-8 text file with the .igl extension. LF and CRLF line endings are equivalent. Two position rules, and only two:

1. a block header starts at column 0;
2. a statement is preceded by at least one space or tab. Beyond that, indentation carries no meaning.

A block ends at the next header or at the end of the file; there is no end marker. A named block carries its name on the header line (RESERVOIR Groundwater). A comment starts with # and runs to the end of the line, on its own or after a statement.

RESERVOIR Groundwater          # a named compartment
    volume 1000 L
    temperature 12 C
    Cr(VI) 0.85 umol/kgw
    delta53Cr -0.2 permil

Headers and keys are case-insensitive (PROCESS, process); identifiers are case-sensitive (Reduction and reduction are two names). By convention, a lower-case initial marks a keyword or an enumerated value (type, first_order), an upper-case initial a name chosen by the author or a chemical species (Groundwater, Cr(VI)). A lower-case block name is accepted with the warning IG010.

There are no reserved words: a word is a keyword by its position. Named entities share a single namespace: a reservoir and a process cannot have the same name (IG102). A secondary block carrying the name of an existing entity extends it: FRACTIONATION Reduction attaches to the process Reduction. The order of blocks in the file is free, and forward references are allowed.

Non-ASCII characters are allowed in quoted strings and in comments; the TITLE line is not a string and stays ASCII. Elsewhere, only µ in a unit (read as u) and ‰ as a unit (read as permil) are accepted and normalised; any other non-ASCII character gives IG006.

Statement forms

The = sign is the only thing that switches a line to evaluation. Without it, no arithmetic is attempted.

02Isotope notation

Two forms, and only two:

• a ratio: <mass><Symbol>/<mass><Symbol>, for example 53Cr/52Cr, 18O/16O, 123Sb/121Sb; the heavy isotope in the numerator;
• a δ value: delta<mass><Symbol>, for example delta53Cr, delta123Sb.

Forms such as Cr53/52 or Sb123 give IG103. Both symbols of a ratio must be identical:

FRACTIONATION Reduction
    isotope 53Cr/52Fe
    epsilon -3.5

Output of igl check for a model containing this block:

error[IG104]: mismatched element symbols across a ratio
  --> model.igl:26:13
   |
26 |     isotope 53Cr/52Fe
   |             ^^^^^^^^^ `Cr` and `Fe` are different elements

1 error(s)

A ratio token is recognised before any arithmetic: 53Cr/52Cr is never a division. In a ratio, R is the abundance of the isotope written in the numerator over that of the isotope written in the denominator, and this is the quantity the engine evolves; δ values are converted on input and recomputed on output.

03Units

Every dimensioned value carries its unit, or receives the one set in the UNITS block. A unit of the wrong dimension gives IG204; a unit left out where several are admissible, IG205. Units are converted to the canonical unit during lowering: an engine only receives canonical units.

alpha is dimensionless; epsilon and 1000ln_alpha are in ‰ and the unit may be left out.

UNITS
    concentration umol/kgw
    time d
    temperature C
    delta permil

04Blocks

Blocks fall into three profiles. The core profile is always accepted; an implementation may support identification without simulation, or the reverse. A block from an unsupported profile gives IG005, never silence.

A unique block written twice gives IG105. Block and property names specific to an implementation start with x_; other names belong to the specification.

Entities are created in a fixed dependency order, independent of their order in the file: META, DATABASE, UNITS, CONDITIONS, STANDARD, PHREEQC, PARAMETERS, SPECIES, ISOTOPES, LAW, RESERVOIR, PROCESS, FRACTIONATION, KINETICS, SAMPLE, MODEL, IDENTIFY, OUTPUT, EXPORT.

05Parameters and expressions

The PARAMETERS block declares global parameters, readable everywhere. A parameter statement in a PROCESS, a RESERVOIR or CONDITIONS declares a parameter local to that block, reached from outside through a two-part qualified name: Reduction.rate_constant. A parameter may read another; a circular reference gives IG107. A local parameter shadowing a global one is accepted with the warning IG108.

PARAMETERS
    k_base = 0.01 1/d
    eps_red = -1.6 permil
    T_ref = 25 C

PROCESS Reduction
    type reduction
    reactant Cr(VI)
    product Cr(III)
    parameter rate_constant = 2 * k_base

RESERVOIR Groundwater
    volume 1 L
    Cr(VI) 1 umol/kgw
    delta53Cr 0 permil

Operators: +, -, *, /, ^. ^ is right-associative and binds tighter than * and /; unary minus applies after the power: -T^2 is -(T^2). Numbers accept scientific notation (1.5e-3).

T is in kelvin in every expression, whatever unit it was declared in: fractionation laws in the literature are written for kelvin.

06Species, isotopes, standards, reservoirs

SPECIES and ISOTOPES

A species is written with an upper-case initial and may contain parentheses and signs: Cr(VI), Fe2+, Sb(V)_ads. A species is a redox pool: its internal speciation is not tracked and does not fractionate.

ISOTOPES declares the tracked ratios and their standard. With mode relative, no standard is required: δ values are differences from the model's origin and the results show the unit permil (relative). The default mode is absolute; a ratio with no resolvable standard, used with a δ value, then gives IG106.

ISOTOPES
    mode relative
    ratio 123Sb/121Sb

SPECIES
    species Sb(V)
    species Sb(V)_ads

STANDARD

A standard is declared by its name, the value of its ratio, the ratio concerned and, optionally, its uncertainty. A standard written in the model takes precedence over one from a database.

STANDARD
    standard NIST-SRM-979 0.11339 ratio 53Cr/52Cr uncertainty 0.00002
    standard VSMOW 0.0020052 ratio 18O/16O

RESERVOIR

CONDITIONS

The conditions of the model: temperature, pressure, pH, Eh, ionic_strength. They set T in expressions, and are used to pick from the databases a factor measured under conditions that contain them.

CONDITIONS
    temperature 9.4 C
    pH 5.23
    Eh 132 mV
    ionic_strength 0.01 mol/kgw

07Processes

type is required and sets the required fields. A process acts within one reservoir (location, inferred when there is only one; otherwise IG211) or moves matter from one reservoir to another (from, into). A product identical to the reactant gives IG214.

Optional fields, for every type: location, from, into, extent, context, regime, law, and local parameter statements.

extent

Fraction of the reactant that reacted, between 0 and 1, as a number or the name of a parameter. A literal is checked during validation, a parameter at run time (IG305). Read only when the model advances by extent; under progress time, it is reported with IG306.

regime

equilibrium or kinetic: how the factor was measured. It narrows the choice in the databases and, with equilibrium, makes the engine apply the closed-system equilibrium law; without it, the engine applies Rayleigh. It is never inferred from the presence or absence of KINETICS.

context

pyrometallurgy, hydrometallurgy, natural or biotic: where the process takes place. It narrows the choice in the databases.

A process is kinetic if a KINETICS block names it; there is no mechanism statement.

RESERVOIR Groundwater
    volume 1000 L
    Cr(VI) 0.85 umol/kgw
    delta53Cr -0.2 permil

RESERVOIR Sediment
    mass 250 kg

PROCESS Removal
    type precipitation
    reactant Cr(VI)
    product Cr(III)
    from Groundwater
    into Sediment
    extent 0.70
    context natural
    regime kinetic

Mixing

The source fractions must sum to 1 within 10⁻⁶ (IG215). The δ of the mixture is weighted by the amounts brought, concentration times fraction, not by the fractions alone.

RESERVOIR UpstreamRiver
    volume 500 L
    Cr(VI) 0.2 umol/kgw
    delta53Cr 0.8 permil

RESERVOIR IndustrialEffluent
    volume 100 L
    Cr(VI) 5 umol/kgw
    delta53Cr 0.1 permil

RESERVOIR DownstreamRiver
    volume 600 L

PROCESS SourceMixing
    type mixing
    source UpstreamRiver 0.55
    source IndustrialEffluent 0.45
    product DownstreamRiver

08Fractionation

FRACTIONATION <Process> attaches to the process of the same name. isotope is required; the factor is given in exactly one of the forms alpha, epsilon, law or law file (two at once: IG213). α is defined as product over reactant: α < 1 means a product depleted in the heavy isotope. No inverted convention is offered.

ε and 1000 ln α are never substituted for each other: their difference exceeds 0.01 ‰ beyond about |ε| = 5 ‰.

FRACTIONATION Reduction
    isotope 53Cr/52Cr
    law
        1000ln_alpha = 3.10 * (10 ^ 6 / T ^ 2) - 2.41

CONDITIONS
    temperature 15 C

A law has alpha, epsilon or 1000ln_alpha as its left-hand side, and reads parameters, T and time. law file "path.csv" points to a law written in a separate file. A LAW block (extended profile) declares a law once for several processes, which name it with law; a FRACTIONATION on the same process takes precedence for the ratio it names.

LAW HighTempCrLaw
    1000ln_alpha = 3.10 * (10 ^ 6 / T ^ 2) - 2.41

PROCESS ThermalReduction
    type reduction
    reactant Cr(VI)
    product Cr(III)
    law HighTempCrLaw

CONDITIONS
    temperature 850 C

Fractionation applies to the matter transferred by the process. The law depends on the regime: closed-system equilibrium if regime equilibrium and the product stays in contact, Rayleigh otherwise. With F the fraction that reacted and f = 1 − F:

A process with no written factor looks for its own in the declared databases (see Factor databases).

09Kinetics

KINETICS <Process> makes the process kinetic. constant is a number with its unit or the name of a parameter, whose unit is used.

KINETICS Reduction
    rate monod
    constant 0.01 1/d
    half_saturation 0.5 umol/kgw

10MODEL: advancing the model

Under progress time, the last step is shortened to land exactly on the stopping condition: step 10 d with until time >= 365 d stops at 365 days, not 370.

MODEL CrReduction
    reservoirs [ Groundwater ]
    processes [ Reduction ]
    step 0.5 d
    until time >= 365 d

KINETICS Reduction
    rate first_order
    constant 0.003 1/d

The stopping condition can also bear on a concentration: until Groundwater.Cr(VI) <= 0.001 umol/kgw. A file contains a single MODEL block; the results name the one that was run.

11OUTPUT and EXPORT

Each variable line adds a column to the results; every sets the recording interval under progress time. The accepted paths:

OUTPUT
    variable time
    variable Groundwater.Cr(VI).remaining
    variable Groundwater.Cr(VI).delta53Cr
    variable Groundwater.delta53Cr
    every 5 d

EXPORT declares one result file per format (isof, csv or json) and its path. The declaration is carried in the intermediate representation; the igl run command of the reference implementation currently writes only the JSON results file described below, and not yet the files declared by EXPORT.

EXPORT
    format csv
    file "cr_plume.csv"

12Factor databases (IGDB)

An IGDB database is a TOML file in the IGDB 1.1 format. It contains a header ([database]: name, version, format version, licence), elements with their abundances, standards, species and fractionation factors. Every numeric value carries its citation.

Where a database is looked for

A path with a separator, or an absolute path, is taken as written, relative to the model. A bare name is looked for in this order: next to the model, in the directory named by the IGL_DATABASES environment variable, in a databases directory near the executable. No network access takes place.

Which entry answers

1. Only entries for the same ratio and the same mechanism remain, compatible with the process's reactant, product, context and regime. An entry silent on one of these axes is compatible with any value.
2. Among them, an entry whose domain contains the model's temperature and pH comes before an entry with no domain, which comes before an entry measured elsewhere.
3. Then the most specific: naming reactant and product weighs more than naming the context, which weighs more than naming the regime.
4. A tie at this stage stops the run and cites the competing entries.
5. An entry applied outside its domain is applied, with the warning IG212.

A STANDARD or a FRACTIONATION in the model takes precedence over the database, with no diagnostic. When a factor comes from a database, the diagnostics in the results cite the entry. The factors of the IsoFind Atlas are published in this format on the IGDB databases page.

13Identification

SAMPLE

SAMPLE OreDeposits
    element Sb
    delta123Sb 0.38 permil
    uncertainty 0.04 permil
    uncertainty_kind standard
    dispersion 0.11 permil
    note "Mean of 14 measurements over 3 deposits"

IDENTIFY

SAMPLE Concentrate
    element Sb
    delta123Sb 0.42 permil
    uncertainty 0.05 permil

SAMPLE Ingot
    element Sb
    delta123Sb 0.70 permil
    uncertainty 0.03 permil

IDENTIFY SmeltingRoute
    source Concentrate
    product Ingot
    mode chain
    candidates [ reduction, evaporation ]
    context pyrometallurgy
    max_chain 3

Computation

• Measured gap Δ_m = δ_p − δ_s; each uncertainty is brought back to one standard deviation (an expanded_k2 value is halved); u = √(u_s² + u_p²); measured interval [Δ_m − k·u − t, Δ_m + k·u + t].
• Interval of a factor: its measured range if the database gives one; otherwise its value ± k times its uncertainty; otherwise the value alone, with its uncertainty reported as unknown. An uncertainty of unstated kind is read as one standard deviation.
• Predicted gap Δ = (δ_s + 1000)·(g − 1), with g the law of the regime: equilibrium, g_product = α/(1 − F + F·α) and g_residue = 1/(1 − F + F·α); Rayleigh, g_product = (1 − f^α)/(1 − f) and g_residue = f^α−1. The g of a chain is the product of the g of its steps.
• An explanation is compatible if its predicted interval meets the measured interval; its residual is the distance between the two intervals. Factors whose domain excludes the temperature or pH of CONDITIONS are set aside before the search, and listed with the reason.
• Compatible explanations are listed first, by number of steps then by citation; incompatible ones follow, by residual. None of these orders is a likelihood. discriminates is false as soon as two or more explanations are compatible.
• An identification that finds no factor to consult for its system is an error, IG307, not an empty set.

14PHREEQC

PHREEQC computes speciation within a redox pool; the isotope engine carries out every transfer between pools and all isotopic accounting. A series mode is read against the model's clock and needs progress time (IG306 otherwise); a read before the first recorded state gives IG404. Without PHREEQC available, IG401, with no substitute computation; this is always the case in the browser. Step-by-step coupling through PhreeqcRM is not defined.

15Shorthand forms

Three blocks of the extended profile expand, during lowering, into a PROCESS and a FRACTIONATION. Both writings produce the same model graph.

RAYLEIGH Distillation
    reservoir Groundwater
    isotope 53Cr/52Cr
    epsilon -1.6
    reactant Cr(VI)
    product Cr(III)

RAYLEIGH describes an open-system distillation, whose product is removed as it forms: the Rayleigh law applies even with an equilibrium factor. ADSORPTION (reactant, sorbent) and EXCHANGE (phase_a, phase_b) expand into PROCESS type adsorption and PROCESS type exchange.

16Diagnostics

A diagnostic carries a code, a severity, a position (file, line, column), the faulty excerpt underlined and, where possible, a suggested correction: for an unknown name, the closest declared name. The compiler does not stop at the first error; it resumes at the next block and reports everything the file allows. Runtime codes (IG3xx, IG4xx) are written to the results file, together with the rows computed before the error. igl explain IG104 explains a code, with a rejected and an accepted example.

The block below contains an error; its diagnostics appear as you type.

17Files produced

Intermediate representation, *.iglir.json

Produced by igl build. The model after resolution, validation, unit conversion and expansion of shorthand forms, with its provenance (path and SHA-256 digest of the source). It is the contract between the language and an engine; it is versioned.

Results, *.results.json

Produced by igl run. format_version; engine (name and version of the code that computed); model (version of the intermediate representation, path and digest of the source, MODEL block run); backends if an external engine was called; columns, each with its name, kind, canonical unit and references resolved to names; rows; diagnostics; identifications. A reader ignores fields it does not know within a major version and refuses a major version it does not implement.

Databases, *.igdb

Read, never written, by the engine; their digest is recorded.

An excerpt of results, for a composition column:

{
  "name": "Groundwater.Cr(VI).delta53Cr",
  "kind": "pool_composition",
  "unit": "permil",
  "reservoir": "Groundwater",
  "species": "Cr(VI)",
  "isotope": "53Cr/52Cr"
}

18Command line

The reference implementation provides the igl command. No version has been published for download yet.

check, parse and build take --profile core|identification|extended, core by default; the core profile stays accepted whichever is declared. A model containing SAMPLE and IDENTIFY is therefore built with --profile identification.

igl check --profile identification sb-smelting.igl
igl build --profile identification sb-smelting.igl
igl run sb-smelting.iglir.json

Environment variable: IGL_DATABASES, directory in which to look for databases named without a path.