.. _d7.01.02-ops:

É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. :ref:`d7.01.02-catalog`:

.. code-block:: python

    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 :

.. code-block:: python

    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.
        """
        args = _F(args)
        info = args.get("INFO", 1)
        # 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 :ref:`d7.01.01-regles`.

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 :

  .. code-block:: shell

    $ ../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 : :ref:`d7.01.01-build-dev`.