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 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 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", "Author", etc.)

  4. Trouver dans la liste de tous les table types celui correpondant à la fonction

    • ⚠️ ATTENTION : Si la fonction ne semble pas avoir de type de table correspondant dans DISHAS, l'ajouter à ce document

  5. Passer au second onglet du formulaire

  6. 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)

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

  8. 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

  9. Appuyer sur le bouton vert ✅ sur la droite de manière à générer les formulaires pour ajouter des informations relatives aux paramètres

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

  11. Une fois le formulaire rempli et que les informations ne nécessitent pas de retouches, cocher "Publish online" et soumettre le formulaire

  12. Un message contenant différents templates de code devrait s'afficher : ils pourront être copiés/collés pour aider à la saisie du code python

Créer la fonction en Python

Ouvrir l'environnement de travail

  1. Ouvrir PyCharm et vérifier le nom de la branche courante (model-definition)

  2. Double-cliquer sur le projet "dishas-block2" dans le menu sur la gauche pour avoir accès aux fichiers

  3. Ouvrir les fichiers kanon/models/models.py, kanon/models/utils.py, kanon/models/tests/test_models.py :

    • Soit dans le menu à gauche qui détaille l'ensemble des fichiers du dossier
    • Soit dans la barre de navigation en haut où les deux fichiers sont déjà ouverts

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)))

Définition de la fonction de test

  1. A la fin du fichier 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
        ],
        
    )

Exécution dans la console

  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

  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

  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

  6. Copier le résultat obtenu et le coller à l'intérieur de la fonction modifiée précédemment 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_sun_equ_1():
    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

Fonction déjà existante

  1. Voir Ouvrir l'environnement de travail

Ajout dans DISHAS

  1. Choisir une fonction dans le fichier kanon/models/models.py, par exemple :
def mercury_anomaly_equation_mean_dist_0(x, param_0):
    """
    Equation of anomaly Mercury at mean distance, rho(cm)=60
    :param x: true argument
    :param param_0: radius of epicycle
    :return: anomaly mercury equation in degree
    """
    return DEG * __math.atan(utils.product_sine_0(x, param_0) / (60 + param_0 * __math.cos(x * RAD)))
  1. Voir Ajout d'un modèle dans DISHAS

Modifier la fonction en Python

Modification de models.py

  1. Dans la bonne catégorie du fichier models.py, copier/coller le bloc de code models.py sauf la dernière ligne et coller le contenu sur la fonction sélectionnée de manière à en remplacer la première ligne ainsi que le commentaire de la fonction
def mercury_ano_equ_mean_dist_0(x, R):
    """
    Equation of anomaly Mercury at mean distance
    :param x: 
    :param r: radius of the epicycle
    :return: anomaly mercury equation in degree
    """
    return DEG * __math.atan(utils.product_sine_0(x, param_0) / (60 + param_0 * __math.cos(x * RAD)))
  1. Comme le nom des paramètres a été modifié, PyCharm souligne en rouge les paramètres à l'intérieur de la fonction. Il faut les renommer avec l'identifiant correspondant tel que défini dans le commentaire de la fonction
    • ⚠️ ATTENTION : Si plusieurs paramètres ont été utilisés, il faut bien être attentif à associer le bon nom de paramètre avec la bonne variable de la fonction
def mercury_ano_equ_mean_dist_0(x, R):
    """
    Equation of anomaly Mercury at mean distance
    :param x: 
    :param r: radius of the epicycle
    :return: anomaly mercury equation in degree
    """
    return DEG * __math.atan(utils.product_sine_0(x, R) / (60 + R * __math.cos(x * RAD)))

Définition de la fonction de test

  1. Aller sur le fichier test_models.py

  2. Rechercher si, sur le curseur à droite de l'écran, se trouve un marqueur orangé indiquant une erreur :

Le marqeur orange est présent Le marqueur n'est pas présent
Cliquer dessus pour se positionner au bon endroit du fichier
Modifier le nom du test de manière à ce qu'il suive la syntaxe test_(FUNCTION-NAME) et modifier aussi le nom de la fonction au sein du test qui est précédée de md. 		Si ce n'est pas le cas, se placer à la fin du fichier et coller le bloc test_models.py de code généré à l'ajout du modèle dans DISHAS

Exécution dans la console

  1. Voir Exécution dans la console

Envoi sur GitHub

  1. Voir Envoi sur GitHub

Fonction pour plusieurs modèles

Certaines fonctions peuvent être utilisées pour plusieurs modèles dans DISHAS : c'est par exemple le cas des modèles qui sont identiques pour plusieurs planètes (e.g. une même fonction pour calculer la latitude de toutes les planètes supérieures). Dans la base de données DISHAS, il faut néanmoins créer un modèle par planète : afin d'éviter trop de redondance dans le code, les fonctions définies pour ce type de modèle vont pouvoir toutes faire appel à une même fonction qui sera définie dans kanon/models/utils.py.

  1. Voir Ouvrir l'environnement de travail

Ajout dans DISHAS

  1. Choisir une fonction dans le fichier kanon/models/utils.py pouvant être utilisée par plusieurs modèles, par exemple l'équation du centre :
def planet_center_equ(x, e):
    """
    :param x:
    :param e: eccentricity
    """
    return DEG * __math.atan(
        2
        * product_sine_0(x, e)
        / (__math.sqrt(60 ** 2 - (product_sine_0(x, e)) ** 2) + e * __math.cos(x * RAD))
    )
  1. Voir Ajout d'un modèle dans DISHAS

Modification de la fonction

  1. Aller dans le fichier kanon/models/models.py et trouver la catégorie correspondant à l'objet astronomique de la fonction que nous voulons ajouter. Pour notre exemple, il s'agit de :
# # # # # # # # # # #
#      JUPITER      #
# # # # # # # # # # #
  1. Sous cette "catégorie", copier l'intégralité du bloc de code models.py indiqué à l'ajout de la fonction sur le site DISHAS :
def jupiter_center_equ(x, e):
    """
    Jupiter center equation
    :param x:
    :param e: eccentricity
    :return:
    """
    # Write function body here
  1. Dans la valeur de retour de la fonction, appeler la fonction définie dans utils.py avec les paramètres corrects
def jupiter_center_equ(x, e):
    """
    Jupiter center equation
    :param x:
    :param e: eccentricity
    :return:
    """
    return utils.planet_center_equ(x, e)

Test de la fonction

  1. Voir Définition de la fonction de test et Exécution dans la console

Envoi sur GitHub

  1. Voir Envoi sur GitHub
Clone this wiki locally