Correspondance Rust ↔ Python

Cette page liste, par module, les structures (exposées en classes Python) et les fonctions libres (exposées en fonctions de module Python). Elle matérialise la règle de Conventions :

• une structure containers::…::Foo est exposée sous le même nom pyrucast.Foo (le wrapper PyO3 interne PyFoo est masqué) ;
• une fonction libre ops::<module>::f est exposée dans le sous-module de même nom : pyrucast.<module>.f. Le module Rust porte le nom du conteneur produit (mesh, node_field, element_field, matrix, model, coords), ou de l’activité quand il ne produit aucun conteneur (measure, geom, export) ; solver est l’exception nommée. Seuls trois verbes vivent au top-level, faute de conteneur produit : save et load (cf. archive) et spill_stats ;
• une surcharge d’opérateur Rust devient un dunder Python (Add → __add__, Index → __getitem__, …) ;
• un constructeur nommé Rust devient un classmethod / constructeur Python.

Les tableaux ci-dessous donnent la forme canonique — la fonction libre. Beaucoup de ces opérations sont aussi exposées comme méthode de leur sujet, selon la règle des trois conditions (Conventions) : premier argument sujet, retour conteneur, sens pour toute instance du type. La règle étant mécanique, la liste n’est pas recopiée ici — elle est vérifiée par un test (tests/python/test_method_exposure.py), qui lit le stub et échoue si une opération éligible perd sa méthode. Ce test porte aussi la liste des exclusions, chacune avec sa raison.

Deux points à connaître, illustrés plus bas : le nom peut changer entre les deux formes (matrix.stiffness(model, mats) / model.stiffness_matrix(mats), element_field.sub_material_field(sub, …) / sub_model.material_field(…)), et les cinématiques (deformation, beam_deformation, shell_deformation, thermal_strain) n’ont pas de méthode : elles exigent des composantes nommées, elles n’auraient pas de sens sur un champ quelconque. von_mises non plus : elle ne s’applique qu’à des contraintes. internal_forces, elle, a sa méthode, sur son sujet le modèle : model.internal_forces(state, solution, materials).

filter_components et rename_component n’ont que la forme méthode (f.filter_components(["u_x"]), f.rename_component("U", "DX")) : un seul conteneur, de petits arguments, une vue dérivée — R1 en fait du vocabulaire du champ, pas un opérateur.

La complétude du miroir est elle aussi vérifiée par un test (tests/python/test_mirror_completeness.py), dans les deux sens : aucun opérateur Rust sans binding Python, et aucune fonction Python sans opérateur Rust. Les dérogations y vivent avec leur raison.

Source de vérité : le #[pymodule] de src/lib.rs (enregistrement des classes et fonctions) et le stub python/pyrucast/_pyrucast/__init__.pyi (signatures typées). Cette page en est un instantané, à régénérer à la main si l’API bouge.

Structures ↔ classes

Le nom de la classe Python est identique au nom de la structure Rust.

Une classe Python n’a pas d’homologue Rust : pyrucast.Array, le tableau 1-D en lecture seule que rendent les fonctions d’échange (export.to_arrays…), lisible sans copie par numpy.asarray.

Quelques types Rust ne sont pas exposés en classes Python : ce sont des détails d’implémentation (SubModelKind, le trait que chaque physique implémente derrière SubModel ; DofOrdering, l’ordonnancement des DOFs d’une SubMatrix ; SubValue, OutOfRange, ValueKind et Interpolated, internes à l’Evolution — une valeur tabulée se passe directement en scalaire ou en champ, la politique hors-plage en chaîne "error"/"clamp"/"extrapolate").

Les sous-objets Sub* (SubMesh, SubFiniteElementSpace, SubNodeField, SubElementField, SubMatrix, SubModel) ne se construisent pas directement côté Python : ce sont des vues obtenues par indexation de leur parent (parent[i]). On construit toujours au niveau parent — Mesh(coords, type), FiniteElementSpace(mesh), ElementField(fes, comps), Matrix.block(...) — ou par l’opérateur qui rend ce parent (model.heat_conduction(fes)), et on compose plusieurs zones avec | (union — Rust : union). Voir la règle « Agrégats : un ou plusieurs » de CONVENTIONS.md.

Exception : SubEvolution. Seul sous-objet à la fois vue (via evolution[i]) et constructible directement — SubEvolution([(t0, v0), (t1, v1), …]) — car une courbe tabulée n’a pas de « parent » géométrique qui la définirait. On compose ensuite les courbes par zone avec | (cf. Évolution).

Fonctions ↔ fonctions

Les fonctions ops prennent leurs conteneurs par référence et renvoient Result<T> (converti en exception Python RuntimeError), sauf celles qui ne peuvent pas échouer (update_contact, mask_sub). Les signatures ci-dessous omettent souvent le & et le Result pour la lisibilité.

ops::mesh — construction et transformation de maillages

Les mailleurs prennent element_type=None en Python : "SEG2" pour line, circle et arc, "QUA4" pour transfinite, et pour sweep la surface du degré des lignes ("QUA4" entre deux SEG2, "QUA8" entre deux SEG3).

Les mailleurs longs (triangulate_surface, pave_surface, grid_surface, grid_surface2, triangulate_volume, pave_volume) ont en Rust une variante *_cancellable qui reçoit un jeton d’interruption ; en Python, l’interruption (Ctrl+C) est câblée dans la fonction nominale.

ops::node_field — opérateurs produisant un champ aux nœuds

internal_forces (BSIG, ∫ Bᵀ σ) et external_forces sont des assemblages, mais leur résultat est un vecteur nodal et non un opérateur : on se range par la sortie.

ops::coords — écriture dans le magasin de coordonnées, calcul dans une configuration

ops::element_field — opérateurs produisant un champ aux points de Gauss

ops::evolution — opérateurs produisant une évolution

ops::measure — réductions à un nombre

ops::field — opérateurs génériques

Leur produit est un conteneur — toujours — mais pas un conteneur déterminé : il dépend de l’argument. La règle « un module par conteneur produit » ne désigne donc pas un module, et ils se rangent par domaine.

La composition de zones passe par l’union (| Python / union Rust) ; l’arithmétique champ + scalaire et champ + champ par les opérateurs +, -, *, /, ** (cf. Opérateurs). Ni l’une ni l’autre n’est une fonction ops — merge(a, b) est juste un alias nommé de a | b.

ops::model — déclaration des physiques

Chaque opérateur rend un Model couvrant tout le support reçu (une zone par sous-espace) ; on compose les physiques hétérogènes avec |. Aucun n’a de forme méthode : le premier argument est le support que le modèle recouvre, pas un sujet qu’on transforme. Seul update_contact, qui transforme un modèle, en a une.

Même ordre partout. Le support d’abord — l’espace EF balayé, ou les maillages qui portent une contrainte, celui qui porte les relations en tête (imposed_mesh, immersed, slave, les termes d’une MPC) —, puis le modèle target auquel on se rattache, puis le reste. La duale d’une variable n’est jamais un argument : elle se lit dans target (Model.dual_of).

Les noms, en Rust. Un nom seul s’emprunte (&str) ; une liste de noms se donne (Vec<String>), parce que le modèle la garde — comme les constructeurs de champs et de matrices. Les termes d’une MPC empruntent leurs maillages : ils restent à l’appelant.

Un argument, deux idiomes. Un argument que Python prend en mot-clé avec valeur par défaut (symmetry="isotropic", strain_measure="linear"), Rust le reçoit explicitement (MaterialSymmetry::Isotropic, StrainMeasure::Linear) : Rust n’a pas d’argument par défaut. Même nom, même ordre ; c’est physics_operator! qui écrit les deux faces. La documentation Rust de chaque fonction dit la valeur que Python prend par défaut, pour qu’un lecteur qui n’écrit que du Rust sache ce que l’autre obtient sans rien dire.

Le pli des lois. Rust nomme la loi par une enum (PlasticLaw, DamageLaw) dans plasticity et damage ; Python déplie les lois en une fonction chacune, que Rust offre aussi. Les dérogations correspondantes sont enregistrées, avec leur raison, dans tests/python/test_mirror_completeness.py.

ops::matrix — assemblage des matrices

Les cinq reposent sur assemble_kind(model, materials, kind: MatrixKind, inputs), le moteur commun des assembleurs, qui n’a pas de binding Python.

ops::solver — résolution

La matrice se suffit : ses lignes de relation portent leur sens (SubMatrix::row_sense), aucun modèle n’est passé à la résolution. L’élimination est une option (relations="eliminate"), et l’ensemble actif s’enclenche de lui-même sur une matrice qui porte des inégalités.

ops::export — export vers des formats externes

spill — le swap utilisateur

Les clés du dictionnaire sont threshold, count, largest, live et peak, en octets ; threshold vaut None quand rien ne déborde. Sur un build qui ne peut pas déborder (feature absente, ou hors Unix), spill_stats existe quand même : tous les compteurs y valent 0. Voir Calculs plus gros que la RAM.

archive — sauvegarde et relecture d’un graphe

Avec spill_stats, les seuls verbes du niveau racine : ils ne produisent aucun conteneur déterminé, mais un dictionnaire de ce qu’on leur a donné.

À l’écriture les types sont connus du compilateur, d’où la tranche de paires ; à la relecture non, d’où la table nommée dont on tire chaque objet avec son type attendu (objets.mesh("clef")?). Voir Sauvegarde et relecture.

ops::geom héberge locate_points (mapping iso-paramétrique inverse, sous le baignage) et project_points (projection au point le plus proche sur une surface, sous le contact) ; ces deux primitives sont internes (API Rust), pas encore exposées en Python — la seule dérogation de module entier enregistrée dans le garde-fou de complétude (tests/python/test_mirror_completeness.py). ops::coloring (coloriage glouton des mailles) et ops::scatter (scatter dans un motif CSR) sont la machinerie de l’assemblage parallèle : API Rust interne, ni opérateurs ni bindings. Le nœud le plus proche, lui, n’est pas un opérateur : c’est la méthode mesh.nearest_node([x, y]), des deux côtés.

Opérateurs (dunders ↔ traits Rust)

Toutes les classes implémentent __repr__ (← Debug, vue structurelle) et __str__ (← Display, vue résumée façon Cast3M) — voir Conventions. Les autres opérateurs, classe par classe :

Arithmétique sur les champs

L’arithmétique (f + s, f + g, …) existe au niveau zone et au niveau agrégat ; les opérations par composante et entre champs sont portées par les traits SubField / Field. Les dunders +, -, *, /, ** dispatchent selon l’opérande droite : un float déclenche l’arithmétique scalaire, un champ du même type l’arithmétique champ + champ (valeur à valeur).

f + s / f + g renvoie un nouveau champ ; += n’est pas surchargé. La composition de zones n’est pas sur + : c’est l’union | (union en Rust, cf. ci-dessous). L’opérateur + est entièrement réservé à l’arithmétique de champ — scalaire (f + 1.0) et champ + champ valeur à valeur (f + g via merge_components/merge_field) ; p. ex. deux champs constants valant 1 s’additionnent en un champ constant valant 2. Pour fusionner des zones avec vérification (et non additionner) : merge(a, b) ≡ a | b.

Algèbre de Matrix / SubMatrix

Matrix.__mul__ dispatche selon l’opérande droite, comme l’arithmétique de champ ci-dessus : un NodeField déclenche le produit matrice-vecteur (mul_field), un float la mise à l’échelle paresseuse du facteur (voir Matrice creuse). / n’existe que pour le facteur (Matrix n’a pas de division matrice-vecteur), et refuse un diviseur nul (ZeroDivisionError) ou non fini (ValueError). Comme pour les champs, tous ces opérateurs renvoient une nouvelle Matrix — jamais de mutation en place.

+ et - additionnent deux opérateurs ; ils ne sont pas la composition (|, ci-dessous), qui écarte un bloc dont elle tient déjà l’emplacement : k | k vaut k, k + k vaut 2k.

Indexation par clé

Protocole séquence — len(x), x[i], for _ in x

Union | (composition d’agrégats)

La composition d’agrégats est l’union : côté Python elle s’écrit | (comme set | set), côté Rust ce sont les méthodes nommées union / union_sub / union_sub_first / union_subs (renvoient Result<…>). Les sous-objets sont partagés (refcount), jamais copiés ; les contraintes de domaine (même Coords pour Mesh, etc.) restent vérifiées.

Sémantique d’union (uniforme pour tous les agrégats) :

1. Déduplication par handle : un sous-objet dont le Handle désigne un objet déjà présent (cf. Handle::same_object) n’est pas ajouté deux fois.
2. Finalisation (Aggregate::finalize) : par défaut un no-op ; les champs la surchargent pour fusionner les zones partageant un même support (voir plus bas).

Vaut pour les sept agrégats (Mesh, FiniteElementSpace, Model, Matrix, NodeField, ElementField, Evolution) plus Node.

Finalisation des champs (fusion par support)

Après l’union par handle, NodeField et ElementField fusionnent les sous-champs définis sur le même support (même Handle<SubMesh> pour NodeField, même Handle<SubFiniteElementSpace> pour ElementField) :

• le sous-champ fusionné porte l’union des composantes ;
• une composante définie par plusieurs sous-champs doit y avoir la même valeur partout (comparaison exacte), sinon | lève une erreur ;
• pour NodeField, une vérification inter-supports finale impose qu’un nœud partagé par des zones de supports différents s’accorde sur toute composante commune.

Ces opérations sont aussi exposées en Rust : ops::node_field::consolidate (NodeField) et ops::element_field::consolidate (ElementField).

+ est réservé à l’arithmétique de champ

L’opérateur + (et -, *, /, **) est l’arithmétique de champ : scalaire (subfield + 2.0 ajoute la valeur à chaque composante) et champ + champ, valeur à valeur (f + g, cf. plus haut). Il n’est jamais utilisé pour composer des agrégats — c’est | qui s’en charge, sans collision.