Nouvelle API C++

[flomnes]

Résumé

Pourquoi ?

Actuellement, les études sont principalement lues depuis des fichiers via des fonctions loadFromFolder.

Dès lors que l'on souhaite créer une étude autrement (en mémoire), on se retrouve bien souvent sur une étude invalide.

L'idée serait d'avoir une API C++ qui permette de s'assurer qu'une étude en mémoire soit valide à la construction, soit empêcher la construction d'une étude invalide.

Cela permettrait de distinguer plus clairement ces étapes

• Lecture des fichiers d'entrée
• Peuplement des structures C/C++ de l'étude en mémoire
• Validation des données d'entrée
• Construction de structures temporaires (runtime, etc.)

Ainsi, le lecteur d'étude sous format de fichiers appellerait ces fonctions de l'API C++. A terme, on pourrait imaginer que d'autres lecteurs/écriteurs d'études fassent leur apparition en utilisant cette même API.

Un autre cas d'usage important est l'écriture de tests in-memory. L'écriture de ces tests serait rendue plus facile par une API claire et concise.

Enfin, on pourrait aussi exposer cette API dans d'autres langages comme Python.

Extensions possibles : récupération des résultats, lancement d'une étude

A discuter, très pratique pour les tests & Python.

[flomnes]

Idée de @guilpier-code : séparer les gros objets en objets plus petits, les fournir aux constructeurs. Cela permet d'écrire des constructeurs plus concis (moins de paramètres)
Exemple

// Avant
class GrosObjet {
GrosObjet(int param1, double param2, double param3);
};
// Après
class PetitObjet1 {
PetitObjet1(int param1);
};
class PetitObjet2 {
PetitObjet2(double param2, double param3);
};
class GrosObjet2 {
GrosObjet2(PetitObjet1&&, PetitObjet2&&);
};

[sylvlecl]

100% ok sur le principe de rassembler dans des petites structures ce qui va ensemble: à identifier au cas par cas dans l'existant je pense!

Pour aider à la construction, un complément peut être de fournir un "builder" pour aider à construire l'objet par appel de plusieurs petites méthodes:

std::unique_ptr<Area> area = AreaBuilder()
        .name("BE")
        ....
        .build();

(y a sûrement mieux comme exemple que Area désolé ...)

[flomnes]

Distinguer les données "métier" des structures temporaires (runtime, uuinfo, scratchpad, etc.)

[sylvlecl]

Oui très important: c'est à la classe responsable de la simulation de maintenir ces données là, pas au modèle de données d'entrée !

[guilpier-code]

Puisqu'on en parle :
uuinfo va bientôt disparaître (si on se fie à son nom, en rapport avec l'UI).
runtime et scratchpad ont des noms génériques qui laissent penser qu'ils ont plusieurs responsabilités. A revoir et à morceler, à mon avis.

[flomnes]

Distinguer le chargement/écriture des autres fonctions-membres

class ThermalClusterList : public ClusterList<ThermalCluster>
{
public:
    ThermalClusterList();
    void calculationOfSpinning();

    /*!
    ** \brief Calculation of Spinning for all thermal clusters (reverse)
    */
    void reverseCalculationOfSpinning();
    //@}

    bool loadFromFolder(Study& s, const AnyString& folder, Area* area);
    bool saveToFolder(const AnyString& folder) const override;
};


// Après
class ThermalClusterList
{
public:
    ThermalClusterList();
    void calculationOfSpinning();

    /*!
    ** \brief Calculation of Spinning for all thermal clusters (reverse)
    */
    void reverseCalculationOfSpinning();
    //@}
}; // class ThermalClusterList

// Placé très haut : interface commune writers
template<class T>
class Writer {
public:
  virtual void write(const T&) = 0;
};

class FileThermalClusterListWriter : public Writer<ThermalClusterList>
{
  void write(const ThermalClusterList&) override;
};

// Même chose pour la sauvegarde

[sylvlecl]

Remarque:
je suis pas sûr qu'il faille un Writer par type d'objet, mais plutôt un writer global pour la study.

Pourquoi:

• selon le format, ça pourra ne pas avoir de sens d'écrire uniquement un sous objet (est-ce qu'écrire un Link tout seul a du sens d'ailleurs, sans parler de format?), et l'ordre des objets pourrait différer d'un format à l'autre. C'est donc le writer global qui est responsable d'écrire chaque objet quand et comme il le souhaite.

• du point de vue des libs "clientes", je pense pas qu'on ait besoin d'autres chose qu'une interface permettant la lecture/écriture globale d'une study ou en tout cas du réseau. Granularité à voir quand même à la cible: peut être séparer les timeseries, certains paramètres ...

[flomnes]

Casser les dépendances en donnant en argument aux fonctions des petits objets

// Avant
Hydro_problem_costs::Hydro_problem_costs(const Data::Study& study)
{
    switch (study.parameters.hydroHeuristicPolicy.hhPolicy)
    {
    case Data::hhpMaximizeGeneration:
        waste = 33 * 68.;
        break;
    case Data::hhpAccommodateRuleCurves:
        waste = 34.0;
        break;
    default:
        waste = 34.0;
        break;
    }
}

// Après
Hydro_problem_costs::Hydro_problem_costs(Data::HydroHeuristicPolicy hhPolicy)
{
    switch (hhPolicy)
    {
    case Data::hhpMaximizeGeneration:
        waste = 33 * 68.;
        break;
    case Data::hhpAccommodateRuleCurves:
        waste = 34.0;
        break;
    default:
        waste = 34.0;
        break;
    }
}

Avant le refactoring, la classe Hydro_problem_costs dépend du gros objet Study via son constructeur. Après, elle ne dépend plus que de l'enum Data::HydroHeuristicPolicy, qui est beaucoup plus petit. Au passage, les tests unitaires sont plus concis : plus besoin de construire un objet Study pour tester la classe Hydro_problem_costs.

[flomnes]

Pouvoir définir les paramètres en chaînant les méthodes (par retour de référence non-constante)

class GrosObjet {
public:
   GrosObjet& setParam1(int param1);
   GrosObjet& setParam2(double param2);
};
GrosObjet obj;
obj.setParam1(223)
   .setParam2(3.13);

[JasonMarechal25]

Je vais peut-être trop loin, mais si l'objectif de faire une palteforme est toujours là, vu le travail de design que ça implique une approche organisée pourrait nous aidée dans notre démarche :
https://github.com/ddd-crew/ddd-starter-modelling-process

[sylvlecl]

Garantir la validité et la cohérence de chaque objet par construction.

Ne pas exposer en public des méthodes ou des champs qui permettent à l'utilisateur des classes de créer des incohérences.

Contres-exemples:

class Area {
...
public:
    AreaName name;
    AreaName id;
...
};

Ici on peut créer une incohérence entre le nom et l'ID. On peut également modifier l'ID ici sans qu'il soit modifié là où c'est nécessaire dans l'étude !

Autre contre-exmple:

class AreaList {
...
public:
    //! All areas by their index
    Area** byIndex;
    //! All areas in the list
    Area::Map areas;
...
};

Ici on peut modifier de manière complètement incohérente la liste par index et la map.
A la place de ceci, on devrait exposer par exemple uniquement les méthodes suivantes:

Area& addArea(std::unique_ptr<Area> area);
Area* getArea(int index) const;
Area* getArea(const std::string& id) const;