Documentation IGL

01Structure d'un fichier

Un modèle est un fichier texte en UTF-8, d'extension .igl. Les fins de ligne LF et CRLF sont équivalentes. Deux règles de position, et seulement deux :

1. un en-tête de bloc commence en colonne 0 ;
2. une instruction est précédée d'au moins une espace ou une tabulation. Au-delà, l'indentation n'a pas de sens.

Un bloc se termine au prochain en-tête ou à la fin du fichier ; il n'y a pas de marque de fin. Un bloc nommé porte son nom sur la ligne d'en-tête (RESERVOIR Groundwater). Un commentaire commence par # et va jusqu'à la fin de la ligne, seul ou après une instruction.

RESERVOIR Groundwater          # un compartiment nommé
    volume 1000 L
    temperature 12 C
    Cr(VI) 0.85 umol/kgw
    delta53Cr -0.2 permil

Les en-têtes et les clés ne distinguent pas les majuscules (PROCESS, process) ; les identifiants, si (Reduction et reduction sont deux noms). Par convention, une initiale minuscule marque un mot-clé ou une valeur énumérée (type, first_order), une majuscule un nom choisi par l'auteur ou une espèce chimique (Groundwater, Cr(VI)). Un nom de bloc en minuscule est accepté avec l'avertissement IG010.

Il n'y a pas de mot réservé : un mot est un mot-clé par sa position. Les entités nommées partagent un seul espace de noms : un réservoir et un processus ne peuvent pas porter le même nom (IG102). Un bloc secondaire qui porte le nom d'une entité existante l'enrichit : FRACTIONATION Reduction s'attache au processus Reduction. L'ordre des blocs dans le fichier est libre, les références en avant sont permises.

Les caractères non ASCII sont admis dans les chaînes entre guillemets et dans les commentaires ; la ligne de TITLE n'est pas une chaîne et reste en ASCII. Ailleurs, seuls µ dans une unité (lu u) et ‰ comme unité (lu permil) sont acceptés et normalisés ; tout autre caractère non ASCII donne IG006.

Formes d'instruction

Le signe = est le seul qui fait passer une ligne en évaluation. Sans lui, aucune arithmétique n'est tentée.

02Notation isotopique

Deux formes, et seulement deux :

• un rapport : <masse><Symbole>/<masse><Symbole>, par exemple 53Cr/52Cr, 18O/16O, 123Sb/121Sb ; l'isotope lourd au numérateur ;
• un δ : delta<masse><Symbole>, par exemple delta53Cr, delta123Sb.

Les formes Cr53/52 ou Sb123 donnent IG103. Les deux symboles d'un rapport doivent être identiques :

FRACTIONATION Reduction
    isotope 53Cr/52Fe
    epsilon -3.5

Sortie de igl check pour un modèle qui contient ce bloc :

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

1 error(s)

Un lexème de rapport est reconnu avant toute arithmétique : 53Cr/52Cr n'est jamais une division. Dans un rapport, R est l'abondance de l'isotope écrit au numérateur sur celle de l'isotope écrit au dénominateur, et c'est cette grandeur que le moteur fait évoluer ; les δ sont convertis à l'entrée et recalculés à la sortie.

03Unités

Chaque valeur dimensionnée porte son unité, ou reçoit celle du bloc UNITS. Une unité de la mauvaise dimension donne IG204 ; une unité omise là où plusieurs sont admissibles, IG205. Les unités sont converties vers l'unité canonique à l'abaissement : un moteur ne reçoit que des unités canoniques.

alpha est sans dimension ; epsilon et 1000ln_alpha sont en ‰ et l'unité peut être omise.

UNITS
    concentration umol/kgw
    time d
    temperature C
    delta permil

04Les blocs

Les blocs se répartissent en trois profils. Le profil core est toujours accepté ; une implémentation peut prendre en charge l'identification sans la simulation, ou l'inverse. Un bloc d'un profil non pris en charge donne IG005, jamais un silence.

Un bloc unique écrit deux fois donne IG105. Les noms de blocs et de propriétés propres à une implémentation commencent par x_ ; les autres noms appartiennent à la spécification.

Les entités sont créées dans un ordre de dépendance fixe, indépendant de leur ordre dans le fichier : META, DATABASE, UNITS, CONDITIONS, STANDARD, PHREEQC, PARAMETERS, SPECIES, ISOTOPES, LAW, RESERVOIR, PROCESS, FRACTIONATION, KINETICS, SAMPLE, MODEL, IDENTIFY, OUTPUT, EXPORT.

05Paramètres et expressions

Le bloc PARAMETERS déclare des paramètres globaux, lisibles partout. Une instruction parameter dans un PROCESS, un RESERVOIR ou CONDITIONS déclare un paramètre local au bloc, que l'on atteint de l'extérieur par un nom qualifié à deux composantes : Reduction.rate_constant. Un paramètre peut en lire un autre ; une référence circulaire donne IG107. Un paramètre local qui masque un global est accepté avec l'avertissement 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

Opérateurs : +, -, *, /, ^. ^ est associatif à droite et lie plus fort que * et / ; le moins unaire est appliqué après la puissance : -T^2 vaut -(T^2). Les nombres acceptent la notation scientifique (1.5e-3).

T est en kelvins dans toute expression, quelle que soit l'unité de déclaration : les lois de fractionnement de la littérature sont écrites pour des kelvins.

06Espèces, isotopes, standards, réservoirs

SPECIES et ISOTOPES

Une espèce s'écrit avec une majuscule initiale et peut contenir des parenthèses et des signes : Cr(VI), Fe2+, Sb(V)_ads. Une espèce est un pool redox : sa spéciation interne n'est pas suivie et ne fractionne pas.

ISOTOPES déclare les rapports suivis et leur standard. Avec mode relative, aucun standard n'est requis : les δ sont des écarts à l'origine du modèle et les résultats affichent l'unité permil (relative). Le mode par défaut est absolute ; un rapport sans standard résoluble, utilisé avec un δ, donne alors IG106.

ISOTOPES
    mode relative
    ratio 123Sb/121Sb

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

STANDARD

Un standard se déclare par son nom, la valeur de son rapport, le rapport concerné et, en option, son incertitude. Un standard écrit dans le modèle l'emporte sur celui d'une base.

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

RESERVOIR

CONDITIONS

Les conditions du modèle : temperature, pressure, pH, Eh, ionic_strength. Elles fixent T dans les expressions, et servent à choisir dans les bases un facteur mesuré dans des conditions qui les contiennent.

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

07Processus

type est obligatoire et fixe les champs requis. Un processus agit dans un réservoir (location, déduit s'il n'y en a qu'un ; sinon IG211) ou déplace la matière d'un réservoir à un autre (from, into). Un produit identique au réactif donne IG214.

Champs facultatifs, pour tous les types : location, from, into, extent, context, regime, law, et des parameter locaux.

extent

Fraction du réactif qui a réagi, entre 0 et 1, en nombre ou en nom de paramètre. Un littéral est contrôlé à la validation, un paramètre à l'exécution (IG305). Lu seulement quand le modèle avance par extent ; sous progress time, il est signalé par IG306.

regime

equilibrium ou kinetic : comment le facteur a été mesuré. Il restreint le choix dans les bases et, avec equilibrium, fait appliquer la loi d'équilibre en système fermé ; sans lui, le moteur applique Rayleigh. Il ne se déduit jamais de la présence ou de l'absence de KINETICS.

context

pyrometallurgy, hydrometallurgy, natural ou biotic : où le processus a lieu. Il restreint le choix dans les bases.

Un processus est cinétique si un bloc KINETICS le nomme ; il n'y a pas d'instruction mechanism.

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

Mélange

Les fractions des sources doivent sommer à 1 à 10⁻⁶ près (IG215). Le δ du mélange est pondéré par les quantités apportées, concentration fois fraction, et non par les fractions seules.

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

08Fractionnement

FRACTIONATION <Processus> s'attache au processus du même nom. isotope est requis ; le facteur se donne sous exactement une des formes alpha, epsilon, law ou law file (deux à la fois : IG213). α est défini produit sur réactif : α < 1 signifie un produit appauvri en isotope lourd. Aucune convention inversée n'est proposée.

ε et 1000 ln α ne se substituent jamais l'un à l'autre : leur écart dépasse 0,01 ‰ au-delà d'environ |ε| = 5 ‰.

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

CONDITIONS
    temperature 15 C

Une loi a pour membre gauche alpha, epsilon ou 1000ln_alpha, et lit les paramètres, T et time. law file "chemin.csv" désigne une loi écrite dans un fichier séparé. Un bloc LAW (profil étendu) déclare une loi une fois pour plusieurs processus, qui la nomment par law ; un FRACTIONATION sur le même processus l'emporte pour le rapport qu'il nomme.

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

Le fractionnement s'applique à la matière transférée par le processus. La loi dépend du régime : équilibre en système fermé si regime equilibrium et que le produit reste au contact, Rayleigh sinon. Avec F la fraction qui a réagi et f = 1 − F :

Un processus sans facteur écrit cherche le sien dans les bases déclarées (voir Bases de facteurs).

09Cinétique

KINETICS <Processus> rend le processus cinétique. constant est un nombre avec son unité ou le nom d'un paramètre, dont l'unité est reprise.

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

10MODEL : faire avancer le modèle

Sous progress time, le dernier pas est raccourci pour tomber exactement sur la condition d'arrêt : step 10 d avec until time >= 365 d s'arrête à 365 jours et non à 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

La condition d'arrêt peut aussi porter sur une concentration : until Groundwater.Cr(VI) <= 0.001 umol/kgw. Un fichier contient un seul bloc MODEL ; les résultats nomment celui qui a été exécuté.

11OUTPUT et EXPORT

Chaque ligne variable ajoute une colonne aux résultats ; every fixe l'intervalle d'enregistrement sous progress time. Les chemins admis :

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

EXPORT déclare un fichier de résultats par format (isof, csv ou json) et son chemin. La déclaration est portée dans la représentation intermédiaire ; la commande igl run de l'implémentation de référence écrit pour l'instant le seul fichier de résultats JSON décrit plus bas, et pas encore les fichiers déclarés par EXPORT.

EXPORT
    format csv
    file "cr_plume.csv"

12Bases de facteurs (IGDB)

Une base IGDB est un fichier TOML, au format IGDB 1.1. Elle contient un en-tête ([database] : nom, version, version du format, licence), des éléments avec leurs abondances, des standards, des espèces et des facteurs de fractionnement. Chaque valeur numérique porte sa citation.

Où une base est cherchée

Un chemin avec séparateur ou absolu est pris tel quel, relatif au modèle. Un nom nu est cherché dans cet ordre : à côté du modèle, dans le dossier de la variable d'environnement IGL_DATABASES, dans un dossier databases proche de l'exécutable. Aucun accès réseau n'a lieu.

Quelle entrée répond

1. Ne restent que les entrées du même rapport et du même mécanisme, et compatibles avec le réactif, le produit, le contexte et le régime du processus. Une entrée muette sur un de ces axes est compatible avec toute valeur.
2. Parmi elles, une entrée dont le domaine contient la température et le pH du modèle passe avant une entrée sans domaine, qui passe avant une entrée mesurée ailleurs.
3. Puis la plus précise : nommer réactif et produit pèse plus que nommer le contexte, qui pèse plus que nommer le régime.
4. Une égalité à ce stade arrête le calcul et cite les entrées en concurrence.
5. Une entrée appliquée hors de son domaine est appliquée, avec l'avertissement IG212.

Un STANDARD ou un FRACTIONATION du modèle l'emporte sur la base, sans diagnostic. Quand un facteur vient d'une base, les diagnostics des résultats citent l'entrée. Les facteurs de l'Atlas IsoFind sont publiés dans ce format sur la page Bases IGDB.

13Identification

SAMPLE

SAMPLE OreDeposits
    element Sb
    delta123Sb 0.38 permil
    uncertainty 0.04 permil
    uncertainty_kind standard
    dispersion 0.11 permil
    note "Moyenne de 14 mesures sur 3 gisements"

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

Calcul

• Écart mesuré Δ_m = δ_p − δ_s ; chaque incertitude est ramenée à un écart type (une valeur expanded_k2 est divisée par deux) ; u = √(u_s² + u_p²) ; intervalle mesuré [Δ_m − k·u − t, Δ_m + k·u + t].
• Intervalle d'un facteur : sa gamme mesurée si la base la donne ; sinon sa valeur ± k fois son incertitude ; sinon la valeur seule, l'incertitude étant déclarée inconnue. Une incertitude de nature non précisée est lue comme un écart type.
• Écart prédit Δ = (δ_s + 1000)·(g − 1), avec g la loi du régime : équilibre, g_produit = α/(1 − F + F·α) et g_résidu = 1/(1 − F + F·α) ; Rayleigh, g_produit = (1 − f^α)/(1 − f) et g_résidu = f^α−1. Le g d'une chaîne est le produit des g de ses étapes.
• Une explication est compatible si son intervalle prédit rencontre l'intervalle mesuré ; son résidu est la distance entre les deux intervalles. Les facteurs dont le domaine exclut la température ou le pH de CONDITIONS sont écartés avant la recherche, et listés avec la raison.
• Les explications compatibles sont listées d'abord, par nombre d'étapes puis par citation ; les incompatibles ensuite, par résidu. Aucun de ces ordres n'est une probabilité. discriminates vaut false dès que deux explications ou plus sont compatibles.
• Une identification qui ne trouve aucun facteur à consulter pour son système est une erreur, IG307, et non un ensemble vide.

14PHREEQC

PHREEQC calcule la spéciation dans un pool redox ; le moteur isotopique fait tous les transferts entre pools et toute la comptabilité isotopique. Un mode series se lit contre l'horloge du modèle et demande progress time (IG306 sinon) ; une lecture avant le premier état enregistré donne IG404. Sans PHREEQC disponible, IG401, sans calcul de remplacement ; c'est toujours le cas dans le navigateur. Le couplage pas à pas par PhreeqcRM n'est pas défini.

15Formes abrégées

Trois blocs du profil étendu se déplient, à l'abaissement, en un PROCESS et un FRACTIONATION. Les deux écritures produisent le même graphe de modèle.

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

RAYLEIGH décrit une distillation en système ouvert, dont le produit est retiré à mesure qu'il se forme : la loi de Rayleigh s'applique même avec un facteur d'équilibre. ADSORPTION (reactant, sorbent) et EXCHANGE (phase_a, phase_b) se déplient en PROCESS type adsorption et PROCESS type exchange.

16Diagnostics

Un diagnostic porte un code, une gravité, une position (fichier, ligne, colonne), l'extrait fautif souligné et, quand c'est possible, une correction suggérée : pour un nom inconnu, le nom déclaré le plus proche. Le compilateur ne s'arrête pas à la première erreur ; il reprend au bloc suivant et rapporte tout ce que le fichier permet. Les codes d'exécution (IG3xx, IG4xx) sont écrits dans le fichier de résultats, avec les lignes calculées avant l'erreur. igl explain IG104 donne l'explication d'un code, avec un exemple refusé et un exemple accepté.

Le bloc ci-dessous contient une erreur ; ses diagnostics s'affichent pendant la frappe.

17Fichiers produits

Représentation intermédiaire, *.iglir.json

Produite par igl build. Le modèle après résolution, validation, conversion des unités et dépliage des formes abrégées, avec la provenance (chemin et empreinte SHA-256 du source). C'est le contrat entre le langage et un moteur ; elle est versionnée.

Résultats, *.results.json

Produits par igl run. format_version ; engine (nom et version du code qui a calculé) ; model (version de la représentation intermédiaire, chemin et empreinte du source, bloc MODEL exécuté) ; backends si un moteur externe a été appelé ; columns, chacune avec son nom, sa nature, son unité canonique et ses références résolues en noms ; rows ; diagnostics ; identifications. Un lecteur ignore les champs qu'il ne connaît pas dans une même version majeure et refuse une version majeure qu'il n'implémente pas.

Bases, *.igdb

Lues, jamais écrites, par le moteur ; leur empreinte est enregistrée.

Un extrait de résultats, pour une colonne de composition :

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

18Ligne de commande

L'implémentation de référence fournit la commande igl. Aucune version n'est encore publiée en téléchargement.

check, parse et build prennent --profile core|identification|extended, core par défaut ; le profil core reste accepté quel que soit celui déclaré. Un modèle qui contient SAMPLE et IDENTIFY se construit donc avec --profile identification.

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

Variable d'environnement : IGL_DATABASES, dossier où chercher les bases nommées sans chemin.