Guides pratiques › Importer des modèles

Guides pratiques

Importer

archec import traduit en arche-lang un modèle fait avec un autre outil. Il lit un projet Arche, un modèle SysML v2, un fichier DBC CAN, des types ASN.1, un robot (URDF ou MJCF), un projet Capella, des exigences Polarion et des fonctions Python. Le résultat est un fichier .arche qu’archec compile aussitôt : vous voyez ses erreurs tout de suite.

Un premier import#

Une base CAN (un fichier DBC) avec deux nœuds et une trame :

VERSION ""

BU_: ECM TCM

BO_ 256 EngineData: 8 ECM
 SG_ EngineSpeed : 7|16@0+ (0.25,0) [0|16383.75] "rpm" TCM

BA_ "GenMsgCycleTime" BO_ 256 10;
archec import bus.dbc -o bus.arche
✓ bus.arche — 1 message, 1 field, 2 component, 1 system, 1 route; 0 note(s)

Dans bus.arche, le message et les deux nœuds donnent ceci :

message EngineData {
  byte-order big
  size 8
  period 10ms
  EngineSpeed: float32 unit rpm at 0 bits 16 scale 0.25
}

component ECM {
  out EngineData: can sends EngineData
}

component TCM {
  in EngineData: can receives EngineData
}

Le fichier contient aussi le type de port can, un système logique, un bus CAN avec un processeur par nœud, et un déploiement qui achemine la trame sur le bus avec id 0x100.

Sans -o, le résultat part sur la sortie standard. Ce qui n’a pas sa place dans le langage n’est pas perdu en silence : les importeurs le gardent en commentaire à l’endroit où il se trouvait (// dbc line N: …) et le signalent dans une note.

Un projet Arche#

archec import <arche-project> -o <dir> réécrit n’importe quel projet Arche en arche-lang. archec diff <a> <b> compare deux projets en tant que données. L’ordre des clés, les guillemets et les valeurs vides ne comptent pas ; l’ordre des listes, si.

Comment l’import procède :

  1. Il compile ce qu’il a écrit et compare le résultat au projet.
  2. Il corrige chaque différence sur la déclaration qui l’a produite.
  3. Il recommence jusqu’à ce que la compilation redonne exactement le projet.
  4. Il écrit ensuite les formes courtes et copie les fichiers auxquels le projet fait référence (assets).

Ce que le langage ne sait pas dire s’écrit avec attr key = value.

Un gros projet a été importé de cette façon : le contrôle d’une antenne sur une Kria KR260, aujourd’hui dans son propre dépôt privé. Il comptait sept fichiers de modèle, 211 composants, 206 exigences avec leurs blocs de vérification, et 54 scénarios avec des fragments alt et loop. Il avait aussi 1280 traces, et des textes en français avec leur traduction anglaise ("Libellé" en "Label"). archec build redonne exactement le projet d’origine.

Un nom entre crochets dans un texte est une référence vérifiée : [REQ-ANT-037], [kria.ps.app.tracking]. Arche la reçoit sous sa propre forme de référence (KRIA260.yaml#kria.ps.app.tracking) : rien ne change donc dans le projet.

Un texte long place sa traduction sur la ligne suivante, en dessous. fmt --simplify découpe ces lignes :

description "Le PS doit faire tourner l'application…"
         en "The PS shall run the application…"

Dans VS Code, un espace de travail qui contient plusieurs projets montre une racine par projet dans les vues Model et Files. examples/ en contient trois.

Un modèle SysML v2#

archec import model.sysml -o model.arche lit un modèle écrit dans la notation textuelle de SysML v2. Le résultat est compilé aussitôt, et ses erreurs sont listées.

L’analyseur est tolérant. Il lit chaque membre d’un corps : un en-tête jusqu’au ;, ou un corps { … }. C’est seulement ensuite qu’il détermine ce qu’est le membre. Ce qu’il ne connaît pas n’est pas une erreur.

SysML v2 arche-lang
le package unique qui entoure le modèle project "Name" (son doc en est la description) ; les packages internes sont des package
part def D :> B component D extends B ; une part def utilisée seulement par une part au premier niveau (part car : Car) devient system Car
part w : Wheel[4], part x { … } part w: Wheel[4], component x { … }
attribute mass = 1200 [kg], attribute g : Gear = Gear::park var mass: float64 = 1200 unit kg, var g: Gear = park
port def P { out item t : Torque; }, port p : ~P port-type P ; in p: P receives Torque (~ inverse le sens des items)
item def M, attribute def S { … }, attribute def T :> Real, enum def E message M, struct S, type T = float64, enum E
une item def aussi utilisée comme donnée (in cmd : Cmd; dans une action, attribute c : Cmd) struct CmdData { … } et message Cmd: CmdData. Un message n’est pas un type : l’action prend donc cmd: CmdData
interface def I { end a : P; end b : ~P; } interface I { messages … } (les items des port defs de ses extrémités)
connect a.p to b.q, connection c connect …, interface i : I connect … a.p -> b.q (orienté pour partir de l’extrémité out), link c a.p -> b.q
flow of M from a.p to b.q a.p -> b.q { carries M }
exhibit state s : S { entry; then A; state A; … } states { state A; … }, l’état initial en premier
transition first A accept e if g then B, accept e then B A -> B on e [g] ; accept after 10 [s] devient un déclencheur en texte, on "after 10 [s]"
action a : Def { in x : Real; out y : Real; }, perform action fn a(x: float64) -> float64
requirement <'R1'> massReq /* Mass */ { doc /* … */ } requirement R1 "Mass" { text "…" } ; une exigence imbriquée derives de son parent
requirement mass : MassReq; (un usage d’une requirement def) requirement mass { text "…" }. Sans texte propre, son texte est le doc de sa définition
satisfy R by x, verify R satisfies R sur la part x (ou sur la définition), verifies R
verification def T { objective { verify R; } } test-plan T { verifies R; case T-1 }
doc /* … */, commentaires // et /* … */ description "…", commentaires

Limites de l’import SysML v2#

  • Les noms sont globaux en arche-lang : les import et les noms qualifiés disparaissent. A::B::C devient C. Deux éléments de même nom dans des packages différents entrent en conflit.
  • Les types de la bibliothèque standard (ScalarValues, ISQ, SI…) deviennent float64, int32, uint32, bool et string. Une grandeur prend son unité dans sa valeur, pas dans son type.
  • Dans Arche, le comportement s’écrit en Python. Une action d’entrée ou de sortie devient un on-enter ou un on-exit vide. L’effet do d’une transition devient un commentaire. Les étapes d’une action sont omises. Une action do ne devient le do de l’état que si la part possède cette action.
  • satisfy R by world.car.engine se place sur la part engine de la définition de car. Elle vaut donc pour toutes les voitures.
  • Les expressions ne sont pas lues. Une garde est recopiée telle quelle. Une valeur par défaut qui n’est ni un littéral ni un nom est omise, avec une note.
  • Rien n’est perdu en silence. Ce qui n’a pas sa place devient un commentaire // sysml line N: … à l’endroit où il se trouvait (N est sa ligne dans le fichier SysML), et une note line N: …. C’est le cas des cas d’utilisation, des calcs, des contraintes, des analyses, des allocations, des vues, de subject et require dans les exigences, des connection defs, des connexions n-aires, et d’une seconde machine à états dans une même part.
  • Les métadonnées (@X, #X, metadata def) sont omises, avec une note.
  • arche-lang n’a pas d’intervalle de multiplicité : [2..4] devient [4]. [*] sur une part est omis.

Un DBC CAN#

archec import bus.dbc -o bus.arche lit une base CAN. Il écrit les mêmes constructions que celles que lit archec gen --target dbc pour écrire un DBC : chacun redonne donc l’autre. Par exemple, prenez le DBC que gen écrit pour examples/autonomous-car, importez-le, puis régénérez-le : vous obtenez le même fichier, octet pour octet.

DBC arche-lang
BO_ 256 EngineData: 8 ECM message EngineData { byte-order …; size 8 }, un format de trame ; l’id 0x100 de la route
SG_ EngineSpeed : 7|16@0+ (0.25,0) [0|16383.75] "rpm" TCM EngineSpeed: float32 unit rpm at 0 bits 16 scale 0.25. at compte le long de la trame comme le fait le format de trame (un signal Motorola à partir de son bit de poids fort). La plupart des signaux prennent le byte-order du message ; les autres indiquent le leur
le signe (-), le facteur et l’offset signed, scale, offset. Un signal mis à l’échelle est un float32 (float64 au-delà de 24 bits). Un signal sans échelle est le plus petit uint ou int qui le contient ; un signal d’un bit est un bool
[min|max] range min..max, sauf si c’est de toute façon ce que portent les bits (ou [0|0])
SIG_VALTYPE_ … : 1 / 2 float32 / float64, envoyé sous forme de ses bits IEEE
VAL_ 512 Gear 0 "Park" 1 "Reverse" … enum Gear { Park = 0, Reverse = 1, … }, nommé d’après sa VAL_TABLE_ quand une table identique existe. Un texte qui n’est pas un nom devient le libellé du littéral
CM_ BO_, CM_ SG_, CM_ BU_ le libellé du message, du champ, du composant et du processeur du nœud
BA_ "GenMsgCycleTime" BO_ 256 10; period 10ms sur le message (gen le réécrit en GenMsgCycleTime)
BU_: ECM TCM component ECM, avec un port out pour chaque trame qu’il envoie et un port in pour chaque trame qu’il reçoit. Le port est can, ou can-fd quand une trame dépasse 8 octets ou que le bus se déclare CAN FD. Chaque nœud est aussi une part du système logique, un processeur de la plateforme sur le bus, et un binaire sur ce processeur dans le déploiement
une trame et ses récepteurs un lien et une route sur le bus pour chaque récepteur, tous à l’id de la trame (gen les réécrit en une seule trame)

Limites de l’import DBC#

  • Un signal multiplexé (m0, m1…) n’a pas sa place. Il devient un commentaire // dbc line N: dans son message, et le multiplexeur (M) est un champ ordinaire.
  • Les groupes de signaux, les variables d’environnement, les tables de valeurs qu’aucun signal n’utilise, et les attributs autres que la période et le type de bus deviennent aussi des commentaires, chacun avec une note.
  • Chaque récepteur reçoit toute la trame. Quand les signaux d’une trame vont à des nœuds différents, gen liste tous les récepteurs sur chaque signal.
  • Vector__XXX (aucun récepteur) est une part à part entière. gen ne la liste pas dans BU_.
  • Une trame envoyée par plusieurs nœuds (BO_TX_BU_) est envoyée par le premier.
  • Une table de valeurs reste un commentaire sur son champ quand le signal est mis à l’échelle, signé, ou plus long que 8 bits.
  • Un flottant IEEE avec un facteur ou un offset les perd : le langage envoie un flottant sous forme de ses bits.
  • Deux trames de même nom forment un seul message quand leurs signaux sont identiques. Sinon, la seconde est renommée (Name_2).
  • Un id étendu est gardé tel quel, avec son bit 31 à 1, dans l’id de la route.
  • Le commentaire propre au fichier (CM_ "…") devient un commentaire en tête. gen ne le réécrit pas.

ASN.1#

archec import types.asn [more.asn…] -o types.arche lit des définitions de types ASN.1. Il lit la partie de X.680 qui décrit les données.

  • Chaque module devient un package.
  • Le IMPORTS … FROM M d’un module est cherché parmi les modules des fichiers fournis.
  • Les noms sont globaux en arche-lang. Un nom que deux modules définissent reçoit un suffixe dans le second (Speed_2).
  • Un tiret devient un tiret bas (Common-Types → Common_Types).
ASN.1 arche-lang
BOOLEAN, REAL bool, float64
INTEGER (0..30000), INTEGER le plus petit uint ou int qui le contient, avec range 0..30000 ; int64 s’il n’est pas borné
ENUMERATED { ok, degraded(5), failed } enum { ok = 0, degraded = 5, failed = 1 }. Les éléments non numérotés prennent le plus petit numéro libre, comme le dit X.680
OCTET STRING (SIZE (4)), OCTET STRING byte[4], bytes
BIT STRING (SIZE (8)) bool[8] (bool[] quand la taille varie)
IA5String, UTF8String, VisibleString, PrintableString… string, avec sa sorte et son SIZE en commentaire
SEQUENCE { a T, b U OPTIONAL, c V DEFAULT x }, SET { … } struct { a: T; b: optional U; c: V = x }
CHOICE { stop NULL, go Speed } union { stop; go: Speed }
SEQUENCE (SIZE (4)) OF T, SEQUENCE SIZE (1..16) OF T T[4], T[] (les bornes en commentaire)
une SEQUENCE qu’aucun autre type n’utilise un message (ce qui est envoyé), ses champs en ligne
un CHOICE qu’aucun autre type n’utilise son union, et message <Name>_MSG: <Name>
une SEQUENCE, un CHOICE ou un ENUMERATED en ligne dans un champ un type à part, nommé d’après sa place (Report_mode)
maxSpeed INTEGER ::= 30000 const maxSpeed = 30000 (pour les valeurs INTEGER, BOOLEAN, REAL et chaînes)
X ::= Y, X ::= INTEGER (…) type X = Y, type X = uint16 range …

Limites de l’import ASN.1#

Chaque point ci-dessous donne lieu à une note qui indique la ligne. Une affectation entière non prise en charge devient aussi un commentaire // asn1 line N: à l’endroit où elle se trouvait.

  • Non pris en charge : les classes et objets d’information (CLASS, &field), les types paramétrés (Pair { T } ::= …), les ensembles de valeurs et COMPONENTS OF.
  • Les valeurs ne sont lues que pour INTEGER, BOOLEAN, REAL et les chaînes.
  • Les nombres nommés d’un INTEGER sont gardés en commentaire.
  • OBJECT IDENTIFIER et les types temporels s’écrivent string.
  • Les seules contraintes lues sont un intervalle de valeurs, une liste de valeurs simples (lue comme leur intervalle) et SIZE. FROM, PATTERN, CONTAINING et WITH COMPONENTS sont omis.
  • Les tags ([3] IMPLICIT) et les marques d’extension (..., [[ … ]]) disent comment le type est encodé et comment il peut évoluer. Ils sont omis. Les ajouts d’extension sont lus comme des composants ordinaires.
  • Un type nommé dans IMPORTS mais absent de tous les fichiers devient bytes.
  • L’encodage (BER, PER, ACN) n’est pas lu. Pour une disposition exacte au bit près, donnez au message un format de trame.

Un robot : URDF et MJCF#

archec import robot.urdf -o robot.arche lit un robot URDF. archec import scene.xml lit un modèle MuJoCo (MJCF). Un fichier .xml est reconnu à son élément racine, <robot> ou <mujoco>.

Le résultat comporte trois choses :

  • un composant pour le robot. Ses corps y sont imbriqués, en suivant l’arbre cinématique. Chaque corps utilise les mots du langage pour les corps : mass, shape, joint. archec gen --target mujoco peut donc le réécrire.
  • une part commands qui envoie aux actionneurs du robot ;
  • un système qui réunit les deux.

Il est écrit comme l’écrit archec fmt, et compilé aussitôt.

component Pendulum "pendulum" {
  solver 1ms                                                   // <option timestep>
  component pole {
    prop hinge = {damping: 0.05}                               // what `joint` does not say
    physical {
      mass 0.3309144262kg                                      // from its geoms, as MuJoCo computes it
      shape capsule 0.02m, 0.5m at 0, 0, -0.25m
      joint hinge y at 0, 0, 1m range -1.570796327..1.570796327 = 0.5
    }

    component servo {
      kind actuator
      prop actuator = {type: position, joint: "hinge"}
      prop kp = 10

      in command: data receives SERVO_CMD                      // value: float64 unit rad range -1.5..1.5
    }
    component angle "angle (jointpos)" {
      kind sensor
      prop sensor = jointpos
      prop joint = "hinge"

      out value: data sends ANGLE                              // value: float64 unit rad
    }
  }
}
Diagramme : pendulum
Ce qu’archec dessine depuis ce code : pendulum
Source arche-lang
un <link> URDF, un <body> MJCF un composant dans celui de son parent, avec mass
sa place dans son parent, et son articulation (URDF revolute, continuous, prismatic, floating, fixed ; MJCF hinge, slide, ball, free) joint hinge y at x, y, z rot r, p, y range lo..hi = start. rot vient du rpy de l’origine URDF, ou du quat, euler, axisangle, xyaxes ou zaxis MJCF. L’amortissement de l’articulation, et les limites effort et velocity d’URDF, vont dans prop <joint> = {…}
<inertial> mass, et prop inertial = {pos, quat, diaginertia | fullinertia}. Sans lui (MJCF), la masse des geoms, telle que MuJoCo la calcule
<collision>, <geom> la première que le langage sait exprimer devient la shape du corps (box, sphere, capsule, cylinder ; avec rot quand elle est tournée dans son corps). Les autres deviennent prop <name> = {geom: …} avec les dimensions de MuJoCo ; un <visual> URDF reçoit visual: true
<site> prop <name> = {site: sphere, pos, size}
<transmission>, une interface de commande <ros2_control>, un actionneur MJCF une part kind actuator dans le corps de son articulation. Son in command reçoit un message dont le champ porte l’unité (rad en position, rad/s en vitesse) et le ctrlrange en range. Aussi prop kp, prop kv, prop actuator = {type, joint, gear…}. commands lui envoie ses ordres
un <sensor> Gazebo ou URDF, un capteur ou une caméra MJCF une part kind sensor dans son corps, avec prop sensor = imu | jointpos | accelerometer…. Son out value envoie un message avec ses unités, à sa fréquence (period). width, height, channels et range tels que les lit la cible gazebo
<include> MJCF, classes <default>, <frame> lus, résolus et fondus dans ce qu’ils contiennent
<option timestep gravity> MJCF, la première <key> solver, prop gravity ; la valeur de départ de chaque articulation (= value)

Unités : les longueurs sont en m, les angles en rad, les masses en kg. Les degrés MJCF sont convertis en radians, et les angles d’Euler et les axes en quaternions.

Repères : le repère d’un corps est celui de la source. Le rot de son articulation le fait tourner dans le repère de son parent. Une rotation autour d’un seul axe s’écrit rot z 90deg ; toute autre rotation s’écrit en roulis, tangage, lacet. L’axe du corps, sa forme, ses enregistrements prop et les corps qu’il contient sont dans ce repère, tels que la source les donne.

Le reste devient un commentaire // urdf: ou // mjcf: à l’endroit où il se trouvait, avec une note : lumières, matériaux, tendons, égalités, paires de contact, plugins Gazebo, articulations mimic, et les keyframes après la première. Un attribut qu’archec ne lit pas donne lieu à une note.

Limites de l’import de robots#

  • Un fichier xacro doit d’abord être développé : xacro robot.urdf.xacro > robot.urdf.
  • Un corps a une seule shape et une seule joint. Ses autres geoms et articulations restent des enregistrements, que gen --target mujoco ne lit pas.
  • Un maillage se réduit à son nom de fichier. Son volume n’est pas calculé : un corps qui n’a qu’un maillage et pas d’<inertial> n’a donc pas de masse.
  • Les valeurs par défaut des actionneurs sont lues d’abord dans l’entrée de classe propre à l’élément, puis dans general.

Capella#

archec capella échange un modèle avec Capella 6.1, dans les deux sens. Il utilise le convertisseur Capella de l’application Arche elle-même (embarqué dans vendor/arche.js). archec et la boîte de dialogue Capella de l’application produisent donc les mêmes fichiers.

archec capella main.arche -o project.zip          # → a Capella project, as the archive Capella imports
archec capella main.arche -o project/             # → the same project as a folder
archec capella model.capella -o model/            # → arche-lang (the .capella's fragments and .aird beside it are read)
archec capella project.zip -o model/              # → arche-lang, from a Capella project exported as an archive

Export#

  1. Le modèle est compilé.
  2. Chaque composant va au niveau Arcadia que nomme son layer : Operational, System, Logical, Physical ou EPBS.
  3. Les données, messages et interfaces vont au niveau le plus abstrait qui les utilise.
  4. Le fichier .capella est vérifié par rapport au métamodèle de Capella 6.1 avant toute écriture. Chaque problème est listé, et le code de sortie vaut 1.

Ce pour quoi Capella n’a pas de place est listé avec la raison. Par exemple : un derives entre deux exigences, ou une étape de scénario sur un échange qui n’est pas exporté.

Pour ouvrir le résultat dans Capella : File › Import › General › Existing Projects into Workspace.

Import#

Le modèle Capella devient d’abord le projet Arche que produit l’import de l’application :

  • un modèle par niveau Arcadia ;
  • disposé comme le dessine le .aird (--no-diagrams saute la mise en page) ;
  • --prefix fixe les noms de fichiers ;
  • --layers oa,sa,la,pa,epbs ne garde que certains niveaux.

Ce projet est ensuite réécrit en arche-lang, comme le fait archec import, puis compilé. Les exigences et les scénarios deviennent des déclarations requirement et scenario. Le reste du modèle est écrit lui aussi :

system-function fly "Fly" {                      // a function, its parts inside it
  system-function steer "Steer" {
    kind route
    allocated dd-sa.drone                         // allocated to a component, by path
    in order "Order" receives command             // its ports and what they carry
  }
}
function-flow read-stick.stick -> steer.order as orders { name "Orders"; carries command }
function-chain branching "Branching" { step or { kind or }; edge or -> steer { when "armed" } }
use-case fly-a-mission "Fly a mission" {          // a capability
  involves dd-sa.pilot, dd-sa.drone, steer, pilot-chain, command
}
property colour { type string; kinds system; group physical }   // a property value's definition
component drone "Drone" { mass 1.5; prop certified = true; prop physical = {colour: "red"} }
Diagramme : Drone
Ce qu’archec dessine depuis ce code : Drone

Où vont les fonctions et les capabilities :

  • Quand un seul niveau a des fonctions, elles vont dans functional.yaml, et les capabilities dans usecases.yaml.
  • Quand plusieurs niveaux ont des fonctions, chaque niveau garde son propre fichier. Ses fonctions, flux et chaînes l’indiquent avec file "dd-la-functions.yaml".
  • Un nom utilisé par deux niveaux est écrit sous forme d’adresse là où il serait ambigu.
  • Les missions restent des attr du fichier des capabilities.

--project dir conserve le projet Arche intermédiaire.

Aller-retour#

L’import enregistre l’origine de chaque élément dans le bloc de données <prefix>-capella.yaml. Un nouvel export redonne aux éléments leurs ids Capella. Cela vaut pour les composants, ports, échanges, fonctions et leurs ports, échanges fonctionnels, chaînes, capabilities, missions et valeurs de propriétés.

Ce que l’export de l’application recrée de zéro reçoit de nouveaux ids : les littéraux des types de données, les régions des machines à états, les participations aux chaînes et les lignes de vie des scénarios. Environ 70 à 80 % des ids d’un modèle survivent.

Python#

archec import x.py traduit des fonctions Python dans le langage d’action, pour qu’elles tournent dans le simulateur et sur un microcontrôleur. archec import <dir> -o <out> le fait pour chaque .py d’un dossier. C’est l’ast de CPython lui-même qui lit le fichier (python3 dans le PATH, ou ARCHEC_PYTHON) ; rien du module ne s’exécute, sauf si vous demandez la vérification.

Prenons numbers.py :

def gcd(a: int, b: int) -> int:
    """
    The greatest common divisor of a and b.

    >>> gcd(48, 18)
    6
    """
    a, b = abs(a), abs(b)
    while b:
        a, b = b, a % b
    return a


def insertion_sort(xs: list[int]) -> list[int]:
    """
    Sorts xs in place.

    >>> insertion_sort([3, 1, 2])
    [1, 2, 3]
    """
    for i in range(1, len(xs)):
        key = xs[i]
        j = i - 1
        while j >= 0 and xs[j] > key:
            xs[j + 1] = xs[j]
            j -= 1
        xs[j + 1] = key
    return xs


def word_count(text: str) -> dict[str, int]:
    """Counts each word."""
    counts: dict[str, int] = {}
    for w in text.split():
        counts[w] = counts.get(w, 0) + 1
    return counts
archec import numbers.py -o numbers.arche --check
  embedded         numbers.py:4 gcd ✓ 8 compared
  embedded         numbers.py:35 insertion_sort ✓ 7 compared
  simulation       numbers.py:52 word_count — the parameter text is a str: strings are not translated
1 module(s), 3 function(s): 2 embedded, 0 embedded-bounded, 1 simulation; checked against Python in simulator, C, Rust: 2 agree, 0 downgraded
✓ 2 file(s) in . — 1 component(s)

numbers.arche contient un composant par module, et une interface des fonctions que d’autres parts peuvent appeler à travers un port :

interface NumbersApi "numbers.py" {
  fn gcd(a: int64, b: int64) -> int64
}

component Numbers "Small number helpers" {
  source "numbers.py"
  code "numbers.py"
  in api: provides NumbersApi

  fn gcd "The greatest common divisor of a and b" (a: int64, b: int64) -> int64 {
    source "numbers.py:4"
    ```arche
    var a_: int64 = a
    var b_: int64 = b
    (a_, b_) = (abs(a_), abs(b_))
    while b_ != 0 {
      (a_, b_) = (b_, floor_mod(a_, b_))
    }
    return a_
    ```
  }

  // it changes xs in place and returns it: here it returns nothing, xs is sorted where it is
  fn insertion_sort "Sorts xs in place" (xs: int64[]) {
    source "numbers.py:35"
    ```arche
    …
    ```
  }

  // simulation only: the parameter text is a str: strings are not translated
  fn word_count "Counts each word" (text: string) {
    simulation-only
    source "numbers.py:52"
  }
}

numbers.test.arche lance les doctests : archec test numbers.test.arche --sim web.

Ce qui est traduit#

Python arche-lang
un module prime_check.py component PrimeCheck, interface PrimeCheckApi de ses fonctions publiques qui ne prennent pas de liste
def f(n: int) -> float, sa docstring fn f "first sentence" (n: int64) -> float64, le reste en description, source "file.py:line"
int, float, bool int64, float64 (--option int=int32, --option float=float32), bool
list[int] comme paramètre int64[], modifié sur place comme en Python ; une fonction qui renvoie la liste qu’on lui a donnée ne renvoie rien
tuple[int, int] comme résultat, return a, b, q, r = f(x) -> (int64, int64), return (a, b), (q, r) = f(x)
[0] * n, [1, 2, 3] un tableau local : de n éléments quand n est une constante, sinon de --option max (64) éléments, avec une vérification que n y tient : la fonction est alors embedded-bounded
a // b, a % b sur des entiers floor_div(a, b), floor_mod(a, b) (arrondi vers le bas, comme Python), ou / et % là où les deux sont connus pour ne pas être négatifs
a / b sur des entiers, x ** y une division flottante ; x * x pour une petite puissance constante, une boucle pour une puissance entière, pow pour une puissance flottante
for i in range(a, b, s), reversed(range(…)), for x in xs, enumerate(xs) for i in a..b step s, une boucle descendante, for x in xs, un compteur
a, b = b, a + b, xs[i], xs[j] = xs[j], xs[i] (a, b) = (b, a + b) : chaque valeur d’abord
sum(…), any(…), all(…) d’un générateur ou d’une liste une boucle avant l’instruction
x if c else y une variable locale fixée par un if
return f(n - 1), return n * f(n - 1) une boucle (un appel terminal), une boucle avec un accumulateur
math.sqrt, sin, cos, atan2, floor, ceil, gcd, isqrt, pi, e, round, divmod, pow(b, e, m) des fonctions intégrées, ou une fonction utilitaire privée du composant (py_isqrt, py_round…)
if n < 0: raise ValueError(…) log "ValueError: …" et le zéro du résultat ; en dessous, n est connu pour ne pas être négatif
isinstance(n, int) d’un n typé ce que dit le type : la vérification est omise

Un paramètre sans annotation de type prend le type que lui donnent ses doctests. Une list[T] générique dans laquelle les doctests trient des nombres et des chaînes devient une liste de nombres.

Embarqué, borné, simulation#

Chaque fonction est classée :

  • embedded : traduite.
  • embedded-bounded : traduite, avec un tableau de taille fixe (--option max).
  • simulation : non traduite. Sa raison est dans un commentaire, et la fonction est simulation-only : elle se lie par son nom au def du .py (code "x.py"), et archec sim l’exécute en Python (sim.md) ; les générateurs embarqués la refusent sur un microcontrôleur. Une fonction qui en appelle une est aussi simulation.

Ce qui rend une fonction simulation : les chaînes, les dicts et les sets ; les listes qui grandissent (append, une nouvelle liste renvoyée) ; les tranches et les listes de listes. Les classes, try, with et les générateurs. Une récursion qui n’est ni un appel terminal ni une accumulation, une fonction dans une fonction, un appel à un autre module. Un paramètre sans type, et ce qu’une vérification a trouvé. --embedded-only laisse de côté les fonctions simulation. --report report.json écrit chaque fonction, sa classe, sa raison, ses doctests et sa vérification ; un petit tableau va sur stderr.

La vérification différentielle#

--check exécute chaque fonction traduite sur les mêmes entrées en Python et dans la traduction, et compare :

  1. les entrées : celles de ses doctests, puis quelques-unes tirées d’une graine (--seed) parmi de petites valeurs (0, 1, 2, 7, -3, 40, 0.5, des listes de 1 à 8 éléments) ;
  2. Python : le module, importé et appelé sur chaque entrée (lib/python/pyimport.py run, 2 s par appel) ; une entrée sur laquelle Python lève une exception n’est pas comparée ;
  3. le simulateur : un banc qui étend le composant appelle la fonction ;
  4. C : archec gen --target c, un harnais qui l’appelle, chaque appel dans un processus à part, compilé avec cc ;
  5. Rust : archec gen --target embassy, son app.rs compilé seul avec rustc.

Un entier se compare exactement ; un flottant à 1e-9 près de sa taille (1e-5 pour float32) ; une liste élément par élément, après l’appel. Un entier que donne Python et que int64 ne contient pas (factorial(21)) relève du domaine de la fonction, ce n’est pas un écart : la fonction reste embedded et le commentaire au-dessus dit à partir d’où (// domain: factorial(21) does not fit in int64). Toute autre différence, un plantage ou une boucle qui ne finit pas, et la fonction est simulation, avec la différence comme raison. --checked-only écarte aussi ce qu’aucune entrée n’a comparé.

Un import d’un autre paquet non installé, fait par le module lui-même, est remplacé par un substitut, pour que les fonctions qui ne l’utilisent pas tournent quand même.

Limites de l’import Python#

  • Les entiers font 64 bits : ce qui les dépasse (une factorielle, 1 << n) donne d’autres résultats. La vérification trouve ceux que les entrées atteignent.
  • Le simulateur représente un entier exactement jusqu’à 2^53 ; au-delà, une valeur n’est comparée qu’en C et en Rust.
  • Un indice négatif (xs[-1] avec une constante devient xs[len(xs) - 1]) ne compte depuis la fin qu’en Python.
  • Un tableau ne passe pas par un port : une fonction qui en prend un n’est pas dans l’interface. Une part qui en a besoin étend le composant.
  • Deux modules du même nom dans deux dossiers : le second reçoit le nom de son dossier devant. --avoid <dir> fait de même pour les noms qu’un autre paquet déclare.
  • round(x, n) arrondit x * 10 ** n : une moitié peut s’arrondir autrement qu’en Python, qui arrondit le décimal exact.

Polarion#

archec polarion écrit les work items d’un projet Polarion sous forme d’exigences. Il les lit depuis un export JSON, ou directement sur le serveur.

Il fonctionne pour n’importe quel projet Polarion :

  • les champs standard sont connus ;
  • un champ personnalisé est reconnu à son nom, ou nommé dans polarion.yaml ;
  • ce qui n’a pas sa place dans le langage est gardé en attr : rien n’est perdu.
archec polarion workitems.json --project main.arche -o spec/polarion.arche   # an export
POLARION_TOKEN=… archec polarion pull main.arche                            # the server
archec polarion pull main.arche --dry-run                                   # the request, not sent

Dans VS Code, Arche: Import from Polarion… fait la même chose :

  • il demande une seule fois le serveur, le projet et la requête, et les garde dans polarion.yaml ;
  • il demande une seule fois le jeton, et le garde dans le stockage secret de VS Code (Arche: Forget the Polarion Token le supprime) ;
  • il écrit le fichier, propose de l’inclure, puis compile.

L’export est ce que l’API REST répond à GET /rest/v1/projects/{p}/workitems?fields[workitems]=@all. archec lit une page {data: [...]}, un tableau de pages, ou le fichier qu’écrit archec polarion pull --save workitems.json. archec import workitems.json fait la même chose que archec polarion workitems.json.

polarion.yaml se trouve à côté de main.arche. Toutes les clés sont facultatives :

url: https://polarion.example.com/polarion   # pull: the server
project: MYPROJ                              # pull: the project id
query: "type:requirement AND NOT status:rejected"
out: spec/polarion.arche                     # where the requirements go (else -o, else stdout)
id: id                                       # id (MYPROJ-123) | puid
documents:                                   # a Polarion document → the project's deliverable
  System Requirements: SRS
modules: [System]                            # only the documents whose id contains one of these
fields:                                      # a field → what it is in the language
  verifMethod: method                        #   description text rationale priority status
  testLevel: attr test-level                 #   category method owner origin, attr <name>, skip
  legacyType: skip
values:                                      # a property's Polarion values → the language's
  status: { inReview: proposed }
  method: { R: inspection }
derives: [parent, satisfies, refines]        # the link roles that are `derives`
Polarion arche-lang
id (ou puid avec id: puid) l’id de l’exigence
title son nom
description, un champ …Rationale (XHTML) description, rationale, en texte brut (paragraphes, retours à la ligne et éléments de liste conservés)
severity (must_have, should_have, nice_to_have, blocker…), sinon priority (90 … 10) priority (critical, high, medium, low)
status (draft, open, inReview, approved, rejected…) status (draft, proposed, approved, implemented, verified, obsolete)
un champ …Category… category (le premier ; tous en attr categories)
un champ …Method… (T, A, I, D, test, analysis…) method
un champ …Owner…, sinon la personne assignée owner
le document (module) document : le livrable que nomme documents:, ou un livrable créé pour lui
id, puid, numéro de plan origin "Polarion MYPROJ-123 · REQ-0085 · SRS-4.2"
un lien dans un rôle de derives:, vers un work item écrit ici ou vers une exigence du projet derives
tout autre lien attr polarion-links = {describes: ["MYPROJ-9"], parent: ["MYPROJ-1"]}
tout autre champ, une énumération personnalisée ou une relation vers un utilisateur attr <field-name> (costCenter → attr cost-center)

Une valeur qui n’a pas de sens dans le langage (un statut weird) est écrite en commentaire et signalée dans une note. Associez-la à une valeur sous values:.

Avec --project (ou pull main.arche) :

  • une exigence que le projet déclare déjà est omise, et les liens vers elle deviennent des derives ;
  • ce que le fichier de sortie déclarait lui-même est réécrit : un nouveau pull le met donc à jour.