Projet : étape 1
"Classes utilitaires"

Concepts nécessaires: classes d'objets, constructeurs/destructeurs, surcharge d'opérateurs.

Fichiers utiles: partie1.zip

Mise en place

Copiez l'archive fournie partie1.zip dans votre répertoire cpp/projet et décompressez-la :

• sous Linux (notamment les VMs de l'EPFL) ou MacOs : dans un terminal, au niveau du répertoire dans lequel se trouve l’archive, tapez la commande unzip partie1.zip
• sous Windows (>=7) : ouvrez l'archive depuis l’explorateur de fichiers et faire un « drag & drop » du contenu vers le répertoire de votre choix.

	===================================================================
	All tests passed (60 assertions in 9 test cases)
      

L'archive fournie contient :

• un sous-répertoire partie1/extlib contenant des outils nécessaires aux procédures de tests que vous allez utiliser;
• un sous-répertoire partie1/res contenant des ressources de base (comme des fichiers de fontes pour votre application graphique);
• un sous-répertoire partie1/src/ dans lequel vous allez placer votre code C++ pour cette étape. Ce sous-répertoire contient déjà :
  • un fichier CMakeLists.txt, déjà rédigé pour cette étape, permettant de compiler votre projet;
  • des programmes de tests situés dans un sous-répertoire partie1/src/Tests/
    L'utilisation de ces tests vous sera expliquée lorsque nécessaire. Ces tests supposent que vous respectiez les prototypes des méthodes qui vous sont suggérés. Si vous voulez changer ces prototypes, il faudra adapter ces fichiers de test en conséquence. De manière générale, consultez toujours les fichiers de tests avant de vous lancer dans le codage de vos classes.
  • un sous-répertoire Utility contenant un fichier Utility.[hpp][cpp]. Ce fichier contient divers petits utilitaires dont le rôle vous sera expliqué en cours d'énoncé. Le répertoire Utility contient également la classe Vec2d permettant de travailler avec des vecteurs à deux dimensions.
    La classe Vec2d servira de base à votre travail à cette étape. Pour connaître les fonctionnalités offertes consultez la documentation de Vec2d.
  • Des sous-répertoires JSON et Random contenant aussi divers utilitaires qui vous seront décrits lorsque nécessaire.
  • Un sous-répertoires Env dans lequel vous placerez le code produit à cette étape: des coquilles vides des premiers fichiers à coder y sont déjà préparés pour vous. .

Pour augmenter la modularité de votre projet, le prototypage des méthodes et la déclaration des attributs devront se trouver dans un fichier avec l'extension .hpp tandis que leurs définitions se trouveront dans un fichier avec l'extension .cpp.

1. Comment éviter les inclusions multiples :

   Les classes que vous allez programmer dans le projet vont se combiner de façon relativement complexe et vous allez parfois devoir inclure de nombreux fichiers .hpp existants au début d'un nouveau fichier .hpp. Si des fichiers ont été inclus de façon redondante dans ces différents .hpp, le compilateur réagira par un message d'erreur. Pour éviter cette situation, il est nécessaire de mettre au début de chaque fichier monfichier.hpp la directive :

   #pragma once
   

2. Convention de nommage pour les fichiers :

   Les fichiers porteront les mêmes noms que les classes qu'ils contiennent : par exemple, les fichiers Animal.[hpp][cpp] contiendront le code relatif à la classe Animal. Il ne s'agit bien sûr que d'une convention.
   Certains systèmes d'exploitation comme Windows sont insensibles à la casse (c'est le cas aussi des VMs de l'EPFL)  : Vec2d.hpp sera donc interprété de la même manière que vec2d.hpp (commençant par un petit "v"). Inclure le fichier vec2d.hpp sera donc interprété comme correct par le compilateur, même si votre fichier s'appelle Vec2d.hpp. Ce n'est pas le cas dans un environnement Unix classique. Faites donc attention à la cohérence car votre projet doit pouvoir s'exécuter partout.
3. Compilation dans un terminal (Linux, MacOs):
   Le matériel fourni est intégrable à QtCreator dans lequel vous pouvez compiler et exécuter. Sous Linux et MacOs, vous pouvez aussi parfaitement l'utiliser en ligne de commande comme indiqué ici.

Modules à programmer

La classe CircularBody

Au cours de leurs déambulations, les hamsters pourront potentiellement croiser des objets d'intérêt comme des sources de nourriture ou encore des obstacles entravant leur liberté de se déplacer. Votre programme devra donc être capable de tester, de façon simple, si deux objets sont en collision. Tester la collision entre deux objets peut s'avérer très complexe selon leurs formes effectives. Nous allons donc, pour simplifier, assimiler les objets à des formes englobantes plus simples lorsqu'il s'agit de gérer les collisions.

La classe CircularBody qu'il vous est suggéré d'écrire ici modélise la représentation géométrique simplifiée que vont prendre les objets simulés pour réaliser les tests de collision. Cette forme est simplement un cercle englobant.

En clair, certaines entités de la vue externes (hamster, tas de nourriture etc.) seront perçus comme de simples cercles lorsqu'il s'agira de tester s'ils se rencontrent ou pas :

il y a « rencontre » entre un hamster et un tas de nourriture si les cercles englobant (en grisé) auxquels ils sont associés se croisent.

Un objet de type CircularBody est caractérisé par  :

• la position de son centre (une paire de coordonnées)  : un Vec2d ;
• son rayon (un double).

#include <Utility/Vec2d.hpp>

Méthodes

Vous doterez la classe CircularBody des méthodes suivantes :

• un constructeur initialisant la position et le rayon de l'objet circulaire au moyen d'un Vec2d et d'un double passés en paramètres (dans cet ordre). Vous ne ferez pour le moment aucun test sur la validité des valeurs passées en paramètres.

• des «getters» (getCenter et getRadius) pour la position du centre et le rayon.

• une méthode isColliding prenant en argument un CircularBody other, et retournant true si other est en collision avec l'instance courante et false sinon. Soient deux CircularBody a et b, a est en collision avec b si la distance entre les centres de a et b est inférieure ou égale à la somme des rayons de a et b;

• une méthode isPointInside prenant en argument un point (de type Vec2d) et retournant true si le point est à l'intérieur de l'instance courante et false sinon. Un point p est à l'intérieur d'un CircularBody body si la distance entre p et body est inférieure ou égale au rayon de body;

• l'opérateur | utilisable comme suit :

  body1 | body2
  

  retournant true si body2 est en collision avec body1 et false sinon. Les objets body1 et body2 sont de type CircularBody;

• l'opérateur > utilisable comme suit :

  body > point
  

  retournant true si point est à l'intérieur de body et false sinon. Les objets body est de type CircularBody et point est de type Vec2d;

[Question Q1.1] Comment coder les deux opérateurs précédemment décrits en évitant toute duplication de code dans le fichier CircularBody.cpp ? Réfléchissez et répondez à cette question dans votre fichier REPONSES.

[Question Q1.2] Quelle surcharge choisissez-vous pour les opérateurs qu'il vous a été demandé de coder jusqu'ici (interne ou externe) et comment justifiez-vous ce choix ? Réfléchissez et répondez à cette question dans votre fichier REPONSES.

[Question Q1.3] Quels arguments de méthodes, parmi celles qu'il vous a été demandé de coder ci-dessus, vous semblent-ils judicieux de passer par référence constante ? Répondez à cette question dans votre fichier REPONSES.

[Question Q1.4] Quelles méthodes, parmi celles qu'il vous a été demandé de coder ci-dessus, vous semblent-ils judicieux de déclarer comme const ? Répondez à cette question dans votre fichier REPONSES.

Programmes de test

Pour tester cette partie du projet vous disposez :

1. de la cible circularBodyTest définie dans le fichier partie1/src/CMakeLists.txt et qui fait appel à plusieurs fichiers;

2. cette cible permet de lancer le programme de test src/Tests/UnitTests/CircularBodyTest.cpp. Ce programme fait appel aux différentes fonctionnalités que vous avez codées dans la classe CircularBody pour contrôler qu'elles sont correctes.

Jetez petit coup d'oeil au fichier CMakeLists.txt pour voir comment est définie cette cible:

#       add_executable (circularBodyTest  ${TEST_DIR}/UnitTests/CircularBodyTest.cpp ${SOURCES} ${CACHE_SOURCES})
#	target_link_libraries(...)

Afin de comprendre le principe de fonctionnement de ces tests, ouvrez le fichier src/tests/UnitTests/CircularBodyTest.cpp pour l'examiner.

Ce programme de test utilise un framework particulier, appelé Catch, permettant de faire ce que l'on appelle dans le jargon de la programmation des tests unitaires. Il s'agit en fait d'écrire des scénarios de tests pour différentes fonctionnalités codées.

Nous vous expliquons ci-dessous le principe de fonctionnement de ces tests.

Principe de fonctionnement des tests unitaires (non graphiques)

Le programme de test fourni dans CircularBodyTest.cpp définit des scénarios (« test case ») permettant de tester les fonctionnalités de la classe CircularBody en faisant appel aux méthodes que l'on vous a demandé d'y coder.

Chaque scénario contient un certain nombre de messages (étiquetés par les mot-clés GIVEN, THEN ou AND_THEN) qui vont décrire les conditions de déroulement des différents tests effectués et leur résultats. Ces messages ne s'afficheront qu'en cas d'échec d'un test.

Si tous les tests d'un scénario se déroulent correctement, vous verrez simplement s'afficher un message ressemblant à ceci :

===============================================================================
All tests passed 

Les tests consistent à vérifier un certain nombre d'assertions exprimées au moyen de fonctionnalités telles que CHECK, CHECK_FALSE, CHECK_APPROX_EQUAL .

Le test fourni ne contient qu'un seul scénario (depuis la ligne 11 jusqu'à le fin), mais il peut y en avoir plusieurs en général. Examinons une partie de ce scénario.

Les lignes 15 et 16 construisent deux CircularBody identiques en position {1,1} et de rayon 2. Les deux objets ainsi construits sont censés être en collision et c'est ce qui est indiqué dans le THEN en ligne 24. Pour tester que votre code fonctionne correctement pour ce cas, le test demande de vérifier 6 assertions :

1. que le centre des objets est conforme à ce qui est attendu;
2. qu'il en va de même pour le rayon;
3. que le premier objet est en collision avec le second (selon les retours de votre méthode isColliding et de votre opérateur operator|);
4. et que le second objet est en collision avec le premier (selon des modalités identiques).

Vous l'aurez compris, un CHECK réussit si l'assertion en paramètre retourne true. De même un CHECK_FALSE (par exemple en ligne 82) réussit si la condition qui lui est passée en argument retourne false.

Supposons que votre méthode isColliding soit mal codée, le lancement du programme de test CircularBodyTest.cpp affichera :

-------------------------------------------------------------------------------
Scenario: Collision
     Given: Two identical circular bodies
      Then: they collide
-------------------------------------------------------------------------------
...
src/Tests/UnitTests/CircularTest.cpp:26: FAILED:
CHECK( o1.isColliding(o2) )
with expansion:
  false                    
...............................................................................

 

Le test affiche donc le nom associé au scénario, les messages associés à GIVEN et THEN pour indiquer ce que l'on a en entrée (deux CircularBody identiques) et ce qui est supposé être vrai dans ce cas ("...they collide") puis la liste des assertions échouées et leur lignes. La partie with expansion indique que l'on a essayé de prouver qu'une assertion était vraie alors que ce qui a été trouvé ("with expansion") est false.

Le lancement de la cible circularBodyTest devrait, une fois le programme corrigé, produire la fin de sortie suivante :

using ./../res/app.json for configuration.

===============================================================================
All tests passed (36 assertions in 1 test case)

  

Note: dans QtCreator cette sortie est visible dans la fenêtre «Application output»

Ceci indique que 36 assertions (CHECK, CHECK_FALSE etc.) ont été lancées avec succès dans le cadre d'un scénario unique ("1 test case").

Notez que dans le cas où les fonctionnalités testées ne sont pas présentes dans votre code, le lancement du test provoquera des erreurs de compilation.

Par exemple, supposez que le constructeur n'est pas codé chez vous conformément à ce qui a été demandé (arguments manquants ou dans le désordre), vous aurez alors un message d'erreur tel que :

error: no matching function for call to 'CircularBody::CircularBody(const Vec2d&, double)'

Test 1 : Fonctionnalités de CircularBody

Le lancement de la cible circularBodyTest devrait donc produire la fin de sortie suivante :

===============================================================================
All tests passed (36 assertions in 1 test case)

La classe Substance

Paramètres de simulation

Avant de nous pencher sur le codage de la classe suivante, un petit détour sur la question de comment représenter les paramètres caractéristiques d'une simulation s'impose.

Il peut en effet y en avoir de très nombreux. Par exemple, quelles dimensions donner aux différents composants graphiques, quelle représentation graphique utiliser pour dessiner les hamsters, etc.

Il est évidemment souhaitable que les valeurs de ces paramètres fassent partie d'un fichier de configuration (plutôt que de les coder « en dur » dans le programme). Ceci nous permettra de faire varier à souhait les exécutions en modifiant simplement le fichier de configuration et donc d'expérimenter facilement de nombreuses situations différentes.

Il existe plusieurs formats standard pour la modélisation de données (XML, JSON, YAML etc), qui d'ailleurs ne sont pas uniquement utilisé dans le contexte de la programmation.

Pour ce projet, nous avons pris le parti d'utiliser le format JSON pour répertorier les paramètres caractéristiques de la simulation.

Les fichiers de configuration du projet sont les fichiers res/appX.json.

Chaque programme que vous lancerez pourra être paramétré par le fichier de configuration comme nous aurons l'occasion de le voir un peu plus tard.

Nous vous fournissons dans le répertoire src/JSON toutes les fonctionnalités nécessaires à la récupération des données depuis un tel fichier.

Dans les fichiers .json, les paramètres sont étiquetés de manière hiérarchique au moyen de chaîne de caractères qui permettent de les décrire.

Par exemple :

{
    "simulation" : {
       ...
        "substance" : {
             "max value" : 200000

           },
        },
      ...
}

La classe utilitaire fournie Config permet d'accéder à la valeur d'un paramètre donné (en l'associant à une constante publiquement accessible). Par exemple la constante substance_max_value permettra d'accéder à la valeur du paramètres étiqueté ["simulation"]["substance"]["max value"] dans le fichier .json.

La classe Application dispose d'un attribut de type Config, qu'elle d'initialise au moyen du bon fichier .json, et c'est par ce biais que vous pourrez accéder aux paramètres par une tournure de ce type :

getAppConfig().substance_max_value;

La classe Substance

Nous avons vu dans la description générale du projet, qu'au niveau interne  :

• la vue sera échantillonnée en cases;
• et que chaque case va représenter un fragment d'organe.

Plus précisément, une case va représenter une portion de ce que l'on appellera la matrice extra-cellulaire (ECM).Cette matrice servira de support aux cellules de l'organe simulé et au système sanguin les irriguant.

Dans notre modèle, c'est par le biais de l'ECM que vont transiter les substances influant sur les différents composants du système :

1. le réseau sanguin va diffuser le glucose et les inhibiteurs sur l'ECM;
2. ces substances seront absorbées depuis l'ECM par les cellules du foie pour leur permettre de produire de l'énergie (avec plus ou moins de succès selon la quantité d'inhibiteurs);
3. les cellules tumorales vont également diffuser une substance, le VGEF, favorisant la croissance du réseau sanguin via l'ECM;
4. cette substance sera récupérée par le système sanguin qui va s'en "nourrir" pour se développer etc..

Toute cette dynamique sera simulée case par case au niveau interne.

Il vous est donc demandé à cette étape du projet de coder une classe Substance représentant de façon synthétique l'ensemble des substances présentes à un moment donné sur une case de l'ECM.

Cette classe sera utilisée par la suite pour mettre en oeuvre les différents phénomènes liés à la diffusion ou l'absorption de glucose, d'inhibiteur et de VGEF.

Une instance de la classe Substance représente donc l'ensemble des substances présentes à un moment donné sur une case de l'ECM.

Elle sera caractérisée par :

• la quantité totale de substances véhiculées (un double). Nous désignerons cette quantité comme étant la concentration totale de substances);
• la fraction de VGEF (pourcentage de VGEF sur la concentration totale);
• la fraction de glucose;
• et la fraction de bromopyruvate (inhibiteur);

Complétez votre classe Substance en y ajoutant :

• un constructeur par défaut initialisant les fractions de toutes les substances (ainsi que leur quantité totale) à zéro;
• un constructeur Substance(double vgef, double glucose, double inhibitor) permettant d'initialiser la concentration totale avec la somme des doubles passés en paramètres. Ce constructeur initialisera aussi de façon adéquate les fractions de chaque substance. Si la concentration totale est négligeable, la quantité de chaque substance sera ramenée à zéro.
  • On considérera que la concentration est négligeable si elle est égale à zéro à une précision donnée près. Vous utiliserez pour coder ce test la fonction isEqual fournie dans le fichier src/Utility/Utility.[hpp][cpp] ainsi que la constante SUBSTANCE_PRECISION fournie dans src/Utility/Constants.hpp.
  • On considérera que la quantité individuelle de chaque substance ne peut dépasser un seuil maximal donné par le paramètre getAppConfig().substance_max_value.

  Que faire si les valeurs passées en argument au constructeur dépassent les seuils limites ?

  Un choix simple ici consiste à faire plafonner les valeurs: si une valeur est inférieure à SUBSTANCE_PRECISION elle devient nulle. Si elle est positive mais dépasse le maximum, on la ramènera au maximum. Vous pourrez utiliser les fonctions min et max de la bibliothèque <algorithm>

• Une méthode isNull() retournant true si les quantités (fraction multipliée par la concentration totale) de chaque substances sont nulles à SUBSTANCE_PRECISION près.
• Un constructeur de copie et un destructeur;
• Un opérateur = de (re)copie;
• Les getters pour chacune des fractions de substances (getFractVGEF, getFractGlucose et getFractInhibitor);
• Un getter getTotalConcentration pour la concentration totale.
• Les opérateurs de comparaison == et !=. Deux instances de Substance seront considérées comme égales si leurs quantités respectives de VGEF, glucose et inhibiteur sont égales, à la précision SUBSTANCE_PRECISION près.
• Un opérateur d'indexation double Substance::operator[](const SubstanceId index) const; permettant d'accéder à la quantité (et non pas fraction) de chaque substance. Cet opérateur sera utilisable comme suit :

  Substance substance(255.0, 432.5, 214.3);
  cout << substance[VGEF] << endl; // affiche 255.0
  cout << substance[GLUCOSE] << endl; // affiche 432.5
  cout << substance[BROMOPYRUVATE] << endl; // affiche 214.3
  

  • SubstanceId est un type énuméré fourni dans le fichier src/Types.hpp;
  • Dans le cas où l'index est inconnu, votre opérateur retournera -1.
• Une surcharge de l'opérateur d'affichage << affichant une instance de Substance sous une forme telle que :

  [VGEF] : 200.0
  [GLUCOSE] : 550.5
  [BROMOPYRUVATE] : 120.0
  

• Une surcharge de l'opérateur += (somme champs à champs de deux instances de Substance)
  A nouveau, il faudra ramener les valeurs aux seuils limites le cas échéant. Si la concentration totale est négligeable, la quantité de chaque substance sera ramenée à zéro.
  Exemple:

  Substance subs1(300.0, 400.0, 200.0);
  Substance subs2(200.0, 100.0, 200.0);
  subs1 += subs2;
  cout << subs1 << endl;
  

  devrait afficher:

  [VGEF] : 500.0
  [GLUCOSE] : 500.
  [BROMOPYRUVATE] : 400.0
  

• Une surcharge de l'opérateur -= (différence champs à champs de deux instances de Substance)
  Pensez à ramener les valeurs aux seuils limites le cas échéant. Si la concentration totale est négligeable, la quantité de chaque substance sera ramenée à zéro.
  Exemple:

  Substance subs1(300.0, 400.0, 100.0);
  Substance subs2(200.0, 100.0, 200.0);
  subs1 -= subs2;
  cout << subs1 << endl;
  

  devrait afficher:

  [VGEF] : 100.0
  [GLUCOSE] : 300.
  [BROMOPYRUVATE] : 0.0
  

• Une surcharge de l'opérateur * multipliant chacune des quantités de substances par un scalaire (en respectant les valeurs limites mentionnées plus haut)

  Exemple:

  Substance subs1(300.0, 400.0, 100.0);
  Substance subs2 = subs1 * 2.0;
  cout << subs2 << endl;
  

  devrait afficher :

  [VGEF] : 600.0
  [GLUCOSE] : 800.
  [BROMOPYRUVATE] : 200.0
  

• Une méthode void update(SubstanceId subId, double c) permettant de multiplier la quantité d'une des substances (celle identifiée par subId) par la valeur c (toujours dans les limites admises). Si la concentration totale obtenue au final est négligeable, la quantité de chaque substance sera ramenée à zéro. Si le coefficient c est négligeable à la précision EPSILON près (constante de Utility/Constants.hpp), la quantité de la substance concernée sera ramenée à zéro.
• Une méthode void uptakeOnGradient(double fraction, Substance& receiver, SubstanceId id); qui prélève de this une fraction du produit identifié par id et l'ajoute à receiver. Si la substance en question est en quantité négligeable (< SUBSTANCE_PRECISION dans this, la méthode uptakeOnGradient ne prélévera rien. Par exemple :

  Substance subs1(100., 200., 300.);
  Substance subs2(300., 200., 100.);
  subs1.uptakeOnGradient(0.5, subs2, GLUCOSE);
  cout << subs1 << endl;
  cout << subs2 << endl;
  

  devrait afficher 

  [VGEF] = 100
  [GLUCOSE] = 100
  [BROMOPYRUVATE] = 300
  
  [VGEF] = 300
  [GLUCOSE] = 300
  [BROMOPYRUVATE] = 100
  

[Question Q1.5] Quels arguments de méthodes, parmi celles qu'il vous a été demandé de coder ci-dessus, vous semblent-ils judicieux de passer par référence constante ? Répondez à cette question dans votre fichier REPONSES.

[Question Q1.6] Quelles méthodes, parmi celles qu'il vous a été demandé de coder ci-dessus, vous semblent-ils judicieux de déclarer comme const ? Répondez à cette question dans votre fichier REPONSES.

Test 2 : Fonctionnalités de Substance

Pour tester la classe Substance vous disposez :

1. de la cible substanceTest définie dans le fichier partie1/src/CMakeLists.txt;

2. cette cible permet de lancer le programme de test src/Tests/UnitTests/SubstanceTest.cpp. Ce programme fait appel aux différentes fonctionnalités que vous avez codées dans la classe Substance pour contrôler qu'elles sont correctes.

Le lancement de la cible substanceTest devrait produire une sortie ressemblant à ceci :

Using ./../res/app.json for configuration.
[VGEF] = 0
[GLUCOSE] = 300
[BROMOPYRUVATE] = 400

[VGEF] = 300
[GLUCOSE] = 200
[BROMOPYRUVATE] = 100

[VGEF] = 45
[GLUCOSE] = 675
[BROMOPYRUVATE] = 43

===============================================================================
All tests passed (77 assertions in 6 test cases)