d7.01.02 Développer une nouvelle macro-commande#

Résumé :

Ce document vient en complément des présentations de la formation au développement. Il détaille les étapes nécessaires à la réalisation de l’exercice d’ajout d’une nouvelle macro-commande.

On propose de créer une nouvelle macro-commande qui convertit un maillage du format ASTER, GIBI ou GMSH au format MED et crée une table contenant quelques informations extraites du maillage.

L’objectif est de savoir :

  • écrire le catalogue de la commande ;

  • accéder aux valeurs des mots-clés depuis Python ;

  • utiliser des commandes au sein de la macro-commande ;

  • appeler l’utilitaire d’impression des messages utilisateur ;

  • extraire des informations du maillage en appelant ses méthodes ;

  • construire et tester son développement.

Remarque :

Les prérequis indispensables avant de commencer à développer est de connaître:

  • le Fortran,

  • le Python (y compris la Programmation Orientée Objet),

  • le gestionnaire de version Git,

  • l’interface GitLab.

Un squelette des fichiers nécessaires est fourni lors de la formation afin de guider les nouveaux développeurs.

Il est conseillé de commencer par la Compilation de la version de référence, puis les Fichiers des exercices.

Catalogue de la macro-commande#

Voici le squelette à compléter du catalogue code_aster/Cata/Commands/conv_mail_med.py:

from ..Commons import *
from ..Language.DataStructure import *
from ..Language.Syntax import *


CONV_MAIL_MED = MACRO(
    nom="CONV_MAIL_MED",
    op=OPS("code_aster.MacroCommands.conv_mail_med_ops.conv_mail_med_ops"),
    sd_prod=...,
    reentrant=...,
    fr=tr("Convertit un maillage ASTER, GMSH ou GIBI au format MED."),
    UNITE_IN=...,
    FORMAT_IN=...,
    UNITE_OUT=...,
    INFO=...,
)

Description du catalogue#

op définit le chemin qui sera utilisé pour importer et lancer la fonction principale de la commande. Le dernier élément est le nom de la fonction, le reste permet d’importer le fichier. L’équivalent serait :

from code_aster.MacroCommands.conv_mail_med_ops import conv_mail_med_ops

Les macro-commandes sont également enrobées avec un « exécuteur » (cf. Exécuteur de la commande), spécifique puisqu’il s’agit de ExecuteMacro au lieu de ExecuteCommand. Il n’y a rien à écrire pour une nouvelle macro-commande.

Les autres arguments sont identiques à ceux d’une commande.

Mots-clés à ajouter#

UNITE_IN est un mot-clé simple obligatoire. Il faut définir le type attendu.

FORMAT_IN est un mot-clé simple, facultatif, qui ne doit accepter qu’une des trois valeurs “ASTER”, “GIBI”, “GMSH”, vaut “ASTER” par défaut.

UNITE_OUT est un mot-clé simple obligatoire. On cherchera dans le catalogue de la commande IMPR_RESU la valeur par défaut utilisée au format MED.

Écriture du code de la macro-commande#

Il s’agit de la fonction principale de la commande déclarée dans le catalogue par l’argument op, cf. Catalogue de la macro-commande:

op=OPS("code_aster.MacroCommands.conv_mail_med_ops.conv_mail_med_ops")

Le fichier associé est donc code_aster/MacroCommands/conv_mail_med_ops.py dont voici le squelette fourni :

from ..Cata.Syntax import _F
from ..CodeCommands import CREA_TABLE, IMPR_RESU, LIRE_MAILLAGE
from ..Messages import UTMESS


def conv_mail_med_ops(self, UNITE_IN, FORMAT_IN, UNITE_OUT, **args):
    """Convert a mesh from ASTER, GMSH ou GIBI format to MED format and
    return some mesh properties.

    Arguments:
        **args (dict): User's keywords.

    Returns:
        Table: Object containing some characteristics of the mesh.

# INFO is mandatory so: # info = args[« INFO »] # or adding INFO in arguments also works

# print the information message UTMESS(…)

# read the input mesh mesh = … # write the mesh into a MED file …

# extract some mesh characteristics nbnodes = mesh. … nbcells = mesh. … # fill the output table tab = CREA_TABLE(

LISTE=(

…

)

) return tab

Description détaillé#

Voir les Règles de programmation.

On débute par l’import des fonctions utilisées, en particulier, les commandes appelées. On note qu’on importe les fonctions des commandes, pas le catalogue.

_F() est utilisé dans le fichier de commandes. Les mots-clés peuvent être fournis aux commandes sous forme de dictionnaire Python. L’objet _F étend le dictionnaire pour faciliter les traitements systématiques.

Les mots-clés obligatoires devraient apparaître dans les arguments de la fonction puisqu’ils doivent être toujours présents (positional arguments). Les mots-clés facultatifs sont passés dans les keywords arguments. On aurait ainsi pu mettre INFO dans les arguments de la fonction. A titre d’exemple, on montre qu’on aurait aussi pu utiliser args["INFO"]. .get() est utilisé pour les mots-clés facultatifs, retourne None (ou la valeur fournie) si le mot-clé est absent.

On propose d’afficher un message pour informer l’utilisateur du travail en cours. La fonction print() est proscrite. Il faut utiliser l’utilitaire UTMESS, cf. code_aster/Messages/Utmess.py.

La lecture du maillage s’effectue en appelant la commande LIRE_MAILLAGE.

La conversion est faite simplement avec IMPR_RESU au bon format.

Pour extraire les informations du maillage, on utilise les méthodes de l’objet Mesh. On peut chercher les méthodes disponibles :

  • dans les exemples/cas-tests (répertoire astest/),

  • dans la documentation embarquée : xdg-open ../install/mpi/share/doc/html/index.html (hors du conteneur),

  • dans les docstrings de l’objet :

    $ ../install/mpi/bin/run_aster
>>> help(CA.Mesh)

Il faut chercher les méthodes qui permettent de récupérer le nombre de noeuds et de mailles.

On termine la fonction en créant la table avec CREA_TABLE. Le cas-test fourni montre le nom des paramètres à créer dans la table. Comme une fonction classique, la table produite, retournée à l’utilisateur, est la valeur de retour de la fonction.

Complétez le squelette et testez votre code : Construire et tester.

Fichiers corrigés#

Catalogue de commandes :

from ..Commons import *
from ..Language.DataStructure import *
from ..Language.Syntax import *

CONV_MAIL_MED = MACRO(
    nom="CONV_MAIL_MED",
    op=OPS("code_aster.MacroCommands.conv_mail_med_ops.conv_mail_med_ops"),
    sd_prod=table_sdaster,
    reentrant="n",
    fr=tr("Convertit un maillage ASTER, GMSH ou GIBI au format MED."),
    UNITE_IN=SIMP(statut="o", typ="I"),
    FORMAT_IN=SIMP(statut="f", typ="TXM", defaut="ASTER", into=("ASTER", "GIBI", "GMSH")),
    UNITE_OUT=SIMP(statut="f", typ="I", defaut=80),
    INFO=SIMP(statut="f", typ="I", into=(1, 2), defaut=1),
)

Corps de la macro-commande code_aster/MacroCommands/conv_mail_med_ops.py :

from ..Cata.Syntax import _F
from ..CodeCommands import CREA_TABLE, IMPR_RESU, LIRE_MAILLAGE
from ..Messages import UTMESS


def conv_mail_med_ops(self, UNITE_IN, FORMAT_IN, UNITE_OUT, **args):
    """Convert a mesh from ASTER, GMSH ou GIBI format to MED format and
    return some mesh properties.

    Arguments:
        **args (dict): User's keywords.

    Returns:
        Table: Object containing some characteristics of the mesh.

# INFO is mandatory so: # info = args[« INFO »] # or adding INFO in arguments also works

# print the information message UTMESS(« I », « MESH_1 », valk=FORMAT_IN, vali=(UNITE_IN, UNITE_OUT))

# read the input mesh mesh = LIRE_MAILLAGE(FORMAT=FORMAT_IN, UNITE=UNITE_IN, INFO=info) # write the mesh into a MED file IMPR_RESU(FORMAT= »MED », UNITE=UNITE_OUT, RESU=_F(MAILLAGE=mesh))

# extract some mesh characteristics nbnodes = mesh.getNumberOfNodes() nbcells = mesh.getNumberOfCells() # fill the output table tab = CREA_TABLE(

LISTE=(

_F(PARA=(« NB_NOEUDS »,), LISTE_I=(nbnodes,)), _F(PARA=(« NB_MAILLES »,), LISTE_I=(nbcells,)),

)

) return tab