Skip to content

Model definition

Jump to bottom
Ségolène Albouy edited this page Apr 20, 2022 · 3 revisions

Définition de modèles dans DISHAS et DIPS

La définition de modèles pour but de constituer un répertoire de fonctions commun aux différents outils développés dans le cadre du projet DISHAS :

  • DTI : outil pour la transcription et l'édition de tables astronomiques. Les modèles y servent à remplir les valeurs tabulaires automatiquement, ainsi qu'à prédire la valeur des paramètres historiques utilisés
  • DIPS : application pour reconstituer le scénario de calcul d'une table et estimer la valeur de ses paramètres astronomiques. Les modèles y servent à établir les valeurs de référence pour les comparer aux entrées de la table historique, ainsi qu'à composer des tables artificielles de toute pièce.
  • Kanon : librairie python pour le calcul à la manière des acteurs historiques.

Afin d'être utilisables par ces différents outils, les modèles ont besoin d'être ajoutés à la base de données de DISHAS, où sont stockées les métadonnées sur le modèle (auteur, explication, etc.), ainsi que les identifiants des différents paramètres utilisés par le modèle. Les modèles doivent aussi être définis comme des fonctions en python, ce qui va permettre de les utiliser dans les différentes applications sus-nommées.

Glossaire

Terme Définition
Fonction Lorsqu'il sera fait référence à une fonction dans ce document, il s'agira d'une fonction python
Modèle Lorsqu'il sera fait référence à un modèle, ce sera pour désigner un enregistrement de "Formula definition" sur la plateforme DISHAS
Type de table Le type de table désigne le type de calcul du modèle (i.e. Equation du temps) ; un même type de table pourra correspondre à plusieurs modèles (c'est-à-dire plusieurs fonctions pour la calcul de l'équation du temps)
Objet astronomique Tous les types de tables sont organisés dans différentes catégories (Soleil, Mercure, Venus, Lune, Mars, Jupiter, Saturne, Astronomie sphérique, Huitième sphère, Eclipse, Trigonométrie)
Ces catégories sont reproduites dans les fichiers python de manière à organiser les différentes fonctions
Argument Le(s) argument(s) représente(nt) les dimensions de la tables : au nombre de 1 lorsque la fonction prend x en argument, et deux avec x, y
Paramètre Les paramètres sont toutes les valeurs astronomiques utilisées par un modèle. Dans les arguments de la fonction, ils sont désignés par leur "Python variable designation" renseignée dans le formulaire sur DISHAS

Fichiers python à modifier

Fichier Utilité
models.py Dans ce fichier sont définis toutes les fonctions correspondant à un modèle dans DISHAS
Les fonctions sont classées dans le fichier selon l'objet astronomique.
utils.py Dans ce fichier sont définies toutes les fonctions utilisées plusieurs fois pour la définition des modèles en python : un morceau de code répété à l'identique dans plusieurs fonctions pourra être reporté en tant que fonction dans ce fichier
Par exemple, la fonction product sinus est fréquemment utilisée et donc existe dans le fichier utils.py bien qu'elle corresponde également à un modèle. Le nom des fonctions de ce fichier n'est pas contraint.
Les fonctions sont classées dans le fichier selon différentes catégories.
test_models.py Dans ce fichier sont définis les tests pour chacune des fonctions du fichier kanon/models/models.py

Ajout de modèles

L'ajout d'un modèle se déroule en deux étapes :

  • l'ajout du modèle dans DISHAS
  • l'ajout du modèle dans le code python de Kanon

Il est préférable de commencer par l'ajout dans DISHAS mais la procédure peut être inversée si la fonction a déja été créée.

Trois différents cas peuvent être rencontrés :

  • Ni la fonction python, ni le modèle dans DISHAS ne sont définis
  • La fonction python existe déjà pour le modèle à créer
  • Il existe une fonction générale pour plusieurs modèles

Ni fonction, ni modèle

Ajout d'un modèle dans DISHAS

  1. Se connecter à l'interface administrateur sur le site DISHAS

  2. Cliquer sur l'onglet Documentation > Model definitions > Add formula definition

  3. Remplir les champs sur le premier onglet du formulaire d'ajout (champs obligatoires : "Name", "Table type", "Author")

  4. Passer au second onglet du formulaire

  5. Insérer une formule LaTeX en cliquant sur le bouton ∑, chaque ligne de la formule doit être définie séparément (à savoir cliquer autant de fois sur le bouton ∑ qu'il y a de ligne définies dans la formule)

    • ⚠️ ATTENTION : la dernière ligne de la formule doit impérativement commencer par f(x) ou f(x,y)

  6. Choisir un nombre d'argument pour la fonction (x / x,y)

  7. Sélectionner les paramètres utilisés par la fonction (Ctrl+Clic ou ⌘+Clic pour sélectionner plusieurs paramètres à la fois)

    • ⚠️ ATTENTION : Si un des paramètres utilisés dans la fonction ne semble pas avoir d'équivalence dans la liste affichées dans DISHAS, l'ajouter à ce document

param

  1. Appuyer sur le bouton vert ✅ pour générer les formulaires liés à ces paramètres

  2. Facultatif : pour chacun des paramètres, remplir les informations les concernants ("LaTeX name", "Default value", "Python variable designation", etc.)

  3. Si le formulaire a bien été rempli et que les informations ne nécessitent pas de retouches, cocher "Publish online" et soumettre le formulaire

  4. Un message contenant différents templates de code devrait s'afficher : ils peuvent être copiés/collés dans le code python afin d'être complétés comme suit

model

Créer la fonction en Python

Définition du modèle

  1. Dans la bonne catégorie du fichier models.py, copier/coller le bloc de code models.py indiqué à l'ajout de la fonction sur le site DISHAS :
def sun_equ_1(x, e):
    """
    Equation of the Sun
    :param x: 
    :param e: solar eccentricity
    """
    # Write function body here
  1. Rédiger le corps de la fonction. Deux variables globales peuvent être utilisées sans être définies RAD (__math.pi / 180) et DEG (1 / RAD)
def sun_equ_1(x, e):
    """
    Equation of the Sun
    :param x: 
    :param e: solar eccentricity
    """
    return DEG * __math.atan(e * __math.sin(x * RAD) / (60 + e * __math.cos(x * RAD)))
  1. Si un morceau de code est fréquemment utilisé dans les fonctions, il est possible de créer une fonction dédiée dans le fichier kanon/models/utils.py, au sein de la bonne catégorie (ici "TRIGONOMETRY"). Par exemple pour la fonction product_sine_0 :
def product_sine_0(x, R):
    """
    :param x:
    :param R: radius/eccentricity
    """
    return R * __math.sin(x * RAD)
  1. Elle peut être appelée dans le fichier models.py en étant précédée de utils. :
def sun_equ_1(x: float, e: float) -> float:
    """
    Equation of the Sun
    :param x: 
    :param e: solar eccentricity
    """
    return DEG * __math.atan(utils.product_sine_0(x, e) / (60 + e * __math.cos(x * RAD)))

Test du modèle

  1. A la fin du fichier kanon/models/tests/test_models.py, copier/coller le contenu du bloc test_models.py généré à l'ajout du modèle dans DISHAS
def test_sun_equ_1():
    assert np.allclose(
        [md.sun_equ_1(x, 6) for x in [0, 45, 70, 180, 270, 310]],
        [
            # Copy test result here
        ],
        
    )

  1. Pour tester la fonction, ouvrir la console python en bas de l'écran.

  2. Copier les imports et variables globales dans l'invite de commande comme écrit dans le bloc de code Python console généré à l'ajout du modèle dans DISHAS console

  3. Appuyer sur Entrée de manière à voir apparaître une nouvelle ligne In[3]

  4. Copier ensuite l'intégralité de la fonction dans l'invite de commande model

  5. Copier la dernière ligne du bloc Python console généré à l'ajout du modèle dans DISHAS et lancer la commande avec Entrée test

  6. Copier le résultat obtenu et le coller à l'intérieur de la fonction créée dans test_models.py

    • assert et allclose() permettent de faire une assertion d'équivalence, nécessaire pour comparer des valeurs flottantes avec des imprécisions d'arrondis selon les environnements d'exécution
def test_model_4_23():
    assert np.allclose(
        [md.sun_equ_1(x, 6) for x in [0, 45, 70, 180, 270, 310]],
        [
            0.0,
            3.7783772159024602,
            5.1917308487097085,
            7.796343665038751e-16,
            -5.710593137499643,
            -4.116924322887793
        ],
    )

Envoi sur GitHub

  1. Aller dans le terminal de PyCharm, et vérifier que l'environnement virtuel est actif (c'est-à-dire que la ligne de l'invite de commande est précédée de (venv))

  2. Sauvegarder les modifications effectuées et les envoyer sur GitHub avec la commande suivante

git add . && git commit -m "Update model definitions"
  1. Des tests automatiques vont se lancer : si des erreurs s'affichent (messages en rouge), relancer la commande ci-dessous* :
git add . && git commit -m "Update model definitions"
  1. Si tous les tests se sont bien déroulés (tout est indiqué comme "Passed"), publier les modifications avec git push. Si le problème persiste, contacter Ségolène Albouy
git push
  1. Si une erreur concernant git (fetch first) apparait, essayer de lancer la commande git pull avant de retenter git push 
git pull

* la procédure de test qui se lance avec la commande git commit modifie parfois les fichiers pour les reformatter (ajouter des espaces, des retours à la ligne, ce genre de choses afin de rendre le code plus lisible). S'il y a eu modification, cela signifie donc qu'il faut à nouveau git add les fichiers (càd les ajouter aux fichiers qu'on veut ajouter dans le commit), puis à nouveau git commit pour conserver un état sauvegardé de ces fichiers modifiés

Clone this wiki locally