Guide du concepteur de Modgen

Transcription

1 Modgen Version Guide du concepteur de Modgen Par Statistique Canada

2

3 Ce manuel a été produit en utilisant Doc-To-Help, de ComponentOne.

4

5 Table des matières Pour bien démarrer 1 Introduction...1 État de la documentation...2 Configuration exigée...2 Aperçu de la microsimulation 3 Aperçu des modèles de microsimulation longitudinale...3 Éléments fondamentaux de tout modèle Modgen...4 Lexique de termes importants...5 Simple exemple de modèle...7 Création d un modèle 8 Assistant de création d un nouveau modèle...8 Organisation du code d un modèle dans les fichiers.mpp...10 Organisation des paramètres de modèle dans les fichiers.dat...10 Organisation des modèles et des scénarios...11 Organisation des descriptions et des notes pour les modèles multilingues...11 Création d'un fichier exécutable de modèle...12 Comment le code Modgen devient un fichier exécutable de modèle...12 Avis de droit d'auteur...13 Création d'un icone personnalisé pour un modèle...14 Exécution d'une simulation du modèle 15 Exécution du fichier exécutable du modèle...15 Initialisation des valeurs de paramètres de modèle dans les fichiers.dat...16 Fichiers de sortie des modèles Modgen...19 Éléments du langage Modgen 20 Aperçu des éléments de Modgen...20 Définition de la nature du modèle de microsimulation...20 Définition des acteurs...21 Définition des états...24 Guide du concepteur de Modgen v v

6 Expressions d'état dérivées utilisées dans les définitions d'acteurs et de tableaux...29 Définition des types de variable de modèle...35 Définition des paramètres de modèle...41 Sous-programmes de validation de paramètres et normalisation des paramètres...50 Étiquettes de symbole...54 Notes relatives aux symboles...56 Documentation...59 Choix de la langue...60 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 63 Aperçu du programme de mise en tableau...63 Expressions de tableau...67 Dimensions de tableau...75 Filtres de tableau...82 Poids de cas et mise à l'échelle de population...85 Tableaux invisibles et dépendances entre les tableaux...86 Tableaux d'utilisateur...87 Tableaux dérivés...91 Agrégations de tableau des modèles de cellule...92 Examen individuel de la vie des acteurs 95 Examen de l'historique des acteurs...95 Commande de suivi...95 État actor_id et opérateur de modulo (reste)...97 États générés par Modgen pour les tableaux...98 Sujets avancés en Modgen 101 Événements Fonctions et macro-instructions d'exécution Accès aux paramètres de modèle dans les fonctions C Liens entre acteurs : accès de variables d'état entre objets du modèle Ensembles d acteurs Moteur de simulation Contrôle de la précision dans les modèles temporels continus de cas Flots indépendants de nombres aléatoires dans les modèles Modgen vi Guide du concepteur de Modgen v10.1.0

7 Exécutions réparties Clonage d'observations : Technique particulière Contrôle des modèles précompilés à partir d'applications externes Outils et techniques de débogage et d optimisation 161 Introduction au débogage Outils et techniques de débogage Techniques d optimisation Matériel de référence 177 Aperçu du résumé des commandes Contenu de la base de données de la documentation de Modgen Contenu de la base de données des sorties Modgen Contenu de la base de données de suivi Modgen Rapport sur l utilisation de mémoire Fichier de journalisation du modèle Annexe: Modgen et l environnement Visual Studio Configuration de Visual Studio 2008 pour les applications Modgen Conversion de modèles Modgen à Visual Studio Barre d outils Modgen 10 dans Visual Studio Élaboration de modèles Modgen en C Sous-dossiers dans les projets de Visual Studio Annexe: Tableaux des anciens et nouveaux noms 220 Guide du concepteur de Modgen v vii

8

9 Pour bien démarrer Introduction Ce guide est une introduction au domaine des modèles dynamiques de microsimulation longitudinale et indique comment de tels modèles peuvent s'élaborer dans le langage Modgen, qui consiste essentiellement en un surensemble du langage de programmation C++, où le concepteur d'applications simule la vie d'un ensemble d'acteurs liés (personne principale et membres de sa famille). Modgen prévoit divers modes de présentation des résultats d'un modèle de simulation, dont un programme de croisement de données qui reporte les résultats en format Access, ceux-ci pouvant par la suite être exportés au format MS Excel ou dans fichier texte, et un programme de suivi qui produit une base de données relationnelles détaillées sur les acteurs en format MS Access. À l'heure actuelle, ce manuel constitue à la fois un guide du concepteur en modélisation Modgen et un document de référence qui renseigne plus en détail sur ce langage. Comme Modgen continue à évoluer, le présent document entend en faire comprendre les grandes lignes et le type de modèles susceptibles d'être élaborés. Dans sa version actuelle, le guide peut être employé par divers concepteurs d'applications. Les utilisateurs désireux d'exécuter des modèles existants en Modgen et d'adapter certains des paramètres de modèles exogènes devront consulter le document intitulé «Guide de l interface visuelle de Modgen». Cependant, les utilisateurs qui désirent modifier les tableaux de sortie et les algorithmes définissant le comportement des acteurs devront lire le présent document au complet. Comme Modgen est un prolongement du langage C++, les concepteurs de modèles devront avoir une certaine connaissance des techniques de programmation structurée. À ceux qui ne possèdent pas une telle connaissance, une foule de notions exposées plus loin seront peu familières. Le guide tente de renseigner le lecteur sur ces questions, mais ne constitue pas une introduction en bonne et due forme de la programmation structurée. Le langage Modgen aide à élaborer trois types de modèles de microsimulation longitudinale. Les deux premières catégories comprennent des modèles temporels discrets et continus de simulation séquentielle d'un certain nombre de cas. À titre d'exemple, citons les modèles LifePaths et POHEM. Le document vise à décrire les divers aspects de la création et de l'exploitation de ces types de modèles. Un autre type de modèle microsimulation basé sur le temps a été élaboré en langage Modgen à Statistique Canada. Modgen prend également en charge les modèles simples de cellule. Ce Guide du concepteur de Modgen v Pour bien démarrer 1

10 type de modèle n'est pas non plus abordé dans le présent guide. Pour plus d informations sur Modgen ou les modèles Modgen, veuillez visiter la page Modgen du site de Statistique Canada ( État de la documentation Modgen évolue continuellement, et de nouvelles fonctionnalités sont ajoutées. Cette version du Guide du concepteur de Modgen a été rédigée pour la version de Modgen. Les utilisateurs qui désirent apprendre les caractéristiques non documentées de ce langage sont priés de s'adresser à microsimulation@statcan.gc.ca. Configuration exigée Modgen a été testé avec le système d exploitation Microsoft Windows XP. Les modèles Modgen étant variés, il est impossible de généraliser les besoins en UCT, espace disque ou mémoire. Modgen a une capacité intrinsèque d utiliser de multiples processeurs, et pour certains modèles, des processeurs additionnels peuvent nettement améliorer la performance. Pour d autres modèles, le facteur limitant est la mémoire physique. Les modèles Modgen exigent l installation de la version appropriée des Composants préalables à Modgen. Les Composants préalables à Modgen sont disponibles sur la page Modgen du site de Statistique Canada ( 2 Pour bien démarrer Guide du concepteur de Modgen v10.1.0

11 Aperçu de la microsimulation Aperçu des modèles de microsimulation longitudinale Cette section donne un aperçu des types de modèles de microsimulation susceptibles d'être élaborés en langage Modgen. On y dresse la liste des éléments clés de modélisation pour toutes les catégories de modèles Modgen. Ces éléments font l'objet d'une plus ample description dans la suite de cet exposé. La présente section décrit en outre un exemple simple de modèle que nous utilisons dans tout le texte pour fournir des exemples de l'agencement fonctionnel des éléments clés d'un modèle valide. Nous signalons que le code source du modèle simple est présenté plus loin dans le document. Dans leur conception la plus générale, les modèles de microsimulation visent à représenter les interactions et les relations entre les micro-éléments d'un système. Les modèles de microsimulation en économique peuvent être transversaux ou longitudinaux. Le premier ensemble de modèles transversaux en politique économique se reportait au régime de l'impôt des particuliers. Les programmes de simulation de l'impôt sur le revenu, qui livrent des estimations de l'incidence d'une réforme fiscale sur les recettes et la répartition des charges fiscales, ont un long passé dans la fonction publique. Plus récemment, les ministres des Affaires sociales ont souvent créé des modèles analogues d'analyse de programmes de transferts comme ceux de l'aide sociale. S'ils sont techniquement complexes, ces modèles demeurent relativement simples sur le plan des concepts. Ils reposent sur les données d'un échantillon représentatif de la population à un moment quelconque (d'habitude avec des données annuelles sur les revenus). On codifie et paramétrise soigneusement les règles et les dispositions du régime de l'impôt sur le revenu ou des transferts sous forme d'algorithmes. La simulation consiste alors à calculer l'impôt à payer ou les prestations de chaque particulier ou famille de l'échantillon par rapport à des règles (statu quo ou réforme hypothétique). Le logiciel permet de comparer ces simulations (cas de référence et variantes), qu'il s'agisse des coûts et des recettes agrégés ou des gagnants et des perdants selon des caractéristiques comme les tranches de revenu ou les catégories de taille de la famille. Des modèles transversaux de ce genre n'ont pas du tout leur place dans un domaine comme celui de la politique des pensions parce que les régimes de retraite tant publics que privés servent ordinairement des prestations longtemps après la retraite (à l'âge de 65 ans), lesquelles dépendent d'une manière complexe des revenus touchés au fil des décennies Guide du concepteur de Modgen v Aperçu de la microsimulation 3

12 avant cette retraite. Ajoutons que les prestations de retraite dépendent aussi dans une large mesure des antécédents sur le plan de l'état matrimonial et de la fécondité (rentes de survivant et d'orphelin) ainsi que de l'état de santé (rentes d'invalidité). L'application des méthodes des modèles de microsimulation longitudinale à l'étude des questions stratégiques des pensions offre un intérêt évident. Par leur conception, les cadres de modélisation longitudinale assimilent les règles des régimes de retraite à analyser et sont capables de créer une vue dynamique d'une population représentative à laquelle ces mêmes règles (cas de référence et variantes) puissent être appliquées. Les prévisions démographiques se prêtent aussi largement à une modélisation de microsimulation longitudinale. On peut clairement voir qu'une analyse des pensions soit centrée sur une ou plusieurs projections démographiques à leur tour fondées sur divers scénarios en matière de fécondité, de mortalité, de migration, etc. Les modèles démographiques ressemblent aux modèles de rentes en ce que des techniques de modélisation relativement simples y prédominent, comparativement à la richesse d'une technique de microsimulation longitudinale. Pour les modèles de microsimulation où un concours purement aléatoire de circonstances détermine quand aura lieu le prochain événement dans la vie d'une personne, on parle de modèles temporels continus (MTC) où l'intervalle de temps entre les événements n'est pas fixe. Les modèles plus rigides qui fixent le laps de temps entre les événements sont appelés modèles temporels discrets (MTD). Ces deux catégories de modèles peuvent être spécifiées en langage Modgen. Éléments fondamentaux de tout modèle Modgen Dans tout modèle élaboré en langage Modgen, il faut spécifier les acteurs et les liens qui les unissent. Les acteurs du modèle se définissent par leurs enfants ou leur ensemble respectif de caractéristiques, lesquelles sont soit des d'états décrivant les acteurs, soit des événements qui transforment les valeurs de ces variables. Ainsi, dans la modélisation d'un régime de retraite, les acteurs sont les personnes (principales), les conjoints, les enfants et les familles. Au nombre des états qui entrent en jeu, on compte l'âge, la situation vis-à-vis de l'activité et le niveau de revenu gagné. Les valeurs évoluent dans le temps au gré des événements. Ainsi, l'événement qui détermine l'âge de la retraite vient changer la valeur de l'état de la situation vis-à-vis de l'activité. Il faut des liens entre les acteurs du modèle si un acteur doit avoir accès aux renseignements relatifs à un autre acteur. Dans une modélisation de régime de retraite, l'acteur «famille» présenterait un état «nombre d'enfants présents dans la famille». Dans cet exemple, nous supposons que le montant de la rente à laquelle l'acteur a droit est fonction du nombre de ses personnes à charge. Ainsi, pour que Modgen puisse calculer le revenu tiré du régime de retraite, il doit avoir accès aux états de l'acteur «famille». Dans d'autres cas, on doit créer des acteurs du même type pour compléter le profil de l'acteur en simulation. Ainsi, dans un modèle ou un acteur «personne» est sur le point de se marier, Modgen créera un autre acteur «personne» qui deviendra le conjoint du premier. Celui-ci est l'acteur personne principal et le conjoint, l'acteur personne secondaire. Pour créer l'acteur secondaire, Modgen doit établir une suite de conjoints possibles jusqu'à la création d'un conjoint au profil approprié. Le système élimine alors les acteurs personnes non retenus comme conjoint. Ce sont là des acteurs 4 Aperçu de la microsimulation Guide du concepteur de Modgen v10.1.0

13 provisoires. Il est essentiel de bien saisir la différence entre acteurs principaux, secondaires et provisoires, car ils se retrouveront tous dans les tableaux si on n'emploie pas les bons filtres. Le langage Modgen voit à ce que les états des acteurs et les liens entre ces derniers soient constamment mis à jour au cours de la simulation. Ainsi, la causalité des états sera toujours actualisée entre les acteurs du modèle. L'utilisateur doit savoir que les acteurs d'un certain type peuvent être nombreux dans un modèle. Ainsi, il peut y avoir plusieurs enfants dans une famille, mais l'acteur enfant ne doit être un défini qu'une fois. Dans ce cas, Modgen suit ces acteurs identiques liés, d'où la possibilité d'avoir accès à l'information relative à chaque enfant actif dans le modèle. Précisons enfin que la simulation du modèle se fait au cas par cas. Par cas, on entend un ensemble d'acteurs liés. La simulation du cas commence par la création des divers acteurs du modèle et se termine quand le dernier acteur cesse d'être actif. Modgen entreprend alors de simuler le cas suivant. Le nombre de cas à simuler est donné par un paramètre de contrôle lors de l'exécution du modèle. Lexique de termes importants Pour savoir élaborer des modèles en langage Modgen, on doit comprendre comment les éléments fondamentaux d'un modèle entrent en interaction. Voici la liste de ces éléments qui sont décrits plus en détail dans la suite de cet exposé. cas Modgen simule un cas à la fois. Un cas est un ensemble d'acteurs aux relations ou liens établis. Le système maintient ces liens entre les acteurs en tout temps pendant la simulation. Un paramètre de contrôle de simulation indique le nombre de cas à simuler. acteurs principaux Ces éléments se situent au cœur même de tout exercice de simulation en Modgen. Les acteurs principaux sont d'ordinaire les personnes ou les ménages créés au début de l'exercice de simulation et dont les caractéristiques évoluent pendant leur vie. Ils se définissent par leurs caractéristiques (états) et les événements qui transforment les états. Ils sont semblables aux objets de classe en C++ et les états et événements sont comme des membres de classe. acteurs secondaires Modgen simule un cas à la fois où un ensemble d'acteurs principaux voit ses états se transformer. Un changement d'état possible est le mariage ou l'union de fait d'un acteur personne. Pour cet événement, le système crée un conjoint approprié. Cet autre acteur personne est appelé acteur secondaire. Une fois créés, ces acteurs peuvent connaître les mêmes événements que les acteurs principaux du même type. Ils sont cependant là pour compléter le profil de l'acteur principal, aussi les filtres doivent-ils les exclure de tous les tableaux produits. acteurs provisoires Dans la création d'un acteur secondaire, Modgen établit un ensemble de candidats qui, s'ils ne deviennent pas le conjoint, sont appelés «acteurs provisoires», n'ayant aucun lien avec un des acteurs principaux du modèle. Comme ces acteurs Guide du concepteur de Modgen v Aperçu de la microsimulation 5

14 sont aussi des acteurs personnes, les filtres doivent les exclure des tableaux. états Ces éléments définissent les caractéristiques des acteurs au cours de leur vie. On les crée par diverses affectations que nous décrirons plus loin. Il peut s'agir de valeurs scalaires ou matricielles (tableaux) selon les types normaux C++ ou les propres types de Modgen. liens du modèle Ces éléments permettent un accès aux états entre acteurs du modèle. Ils sont analogues aux pointeurs symétriques C++ entre classes. paramètres de modèle Ce sont des éléments exogènes qui figurent dans les fichiers.dat que lit le programme d'exécution du modèle. Les paramètres de modèle spécifient généralement les éléments de l'exercice de simulation, qu'il s'agisse des règles d'admissibilité d'un régime de retraite ou de taux estimatifs de participation à un nouveau programme social. Les paramètres sont des valeurs scalaires ou matricielles selon les types normaux C++ ou les propres types de Modgen. types Ces éléments définissent la nature des états et des paramètres de modèle. Ce sont les types normaux C++ (int, double, etc.) ou des types particuliers Modgen (range, logical, partition ou classification. événements Ces éléments sont des prototypes de fonctions spéciales où Modgen modifie les caractéristiques des acteurs en changeant leurs états. prototypes de fonctions Ces éléments sont des fonctions types C++ appelées par les fonctions d'événement. Ils forment aussi la base du contrôle de simulation. paramètres de contrôle de simulation Ces éléments contrôlent la nature de la simulation de modèle, et non pas les éléments du programme en simulation. Citons à titre d'exemple le nombre de cas à simuler, la valeur de départ du générateur de nombres aléatoires ou le coefficient de pondération de cas en simulation. initialisateur d'état Cet élément sert à initialiser un état dans la définition de l'acteur correspondant. expression d'identité Cet élément maintient les identités entre états en tout temps pendant l'exercice de simulation. De tels éléments peuvent seulement figurer dans la définition de l'acteur. fonctions spéciales Modgen 6 Aperçu de la microsimulation Guide du concepteur de Modgen v10.1.0

15 Ces éléments servent parfois dans les expressions d'identité à établir les relations entre états. Simple exemple de modèle Ce guide inclut plusieurs exemples de code tiré d un modèle simple de microsimulation longitudinale appelé simpex afin d illustrer un grand nombre d'éléments du langage Modgen. Dans ce modèle, une personne seule demeure dans un logement. La valeur initiale de l'état d'invalidité physique de l'intéressé (aucune, légère, moyenne ou grave) est «aucune». Cet état d'invalidité peut changer quand il atteint l'âge de 60 ans. Le revenu annuel est fondé sur le degré d'invalidité ( $ par an pour «aucune», $ pour «légère», $ pour «moyenne» et 0 $ pour les années où un adulte souffre d'un grave handicap). L'intéressé supporte les frais d'entretien de son logement. On dégage un solde annuel pour le logement en soustrayant un coût annuel constant du revenu annuel de l'adulte. Voici comment se formule ce modèle en Modgen. D'abord, il y a deux acteurs, à savoir le logement et la personne. L'acteur logement contient les états relatives au coût de logement(dwelling_cost) et un seul événement pris en compte tous les ans permet de calculer la variable des soldes annuels (dwelling_balance). L'acteur personne a les états du sexe, du revenu et de l'invalidité. Comme il ne se marie jamais, aucun acteur personne provisoire n'est créé dans ce modèle. Modgen calcule automatiquement l'âge de l'intéressé. Pour l'acteur personne, il y a d'autres états servant à communiquer d'autres renseignements par le programme de croisement de données. Comme l'acteur logement, l'acteur personne présente une fonction d'événement destinée d'année en année à la détermination de l'état d'invalidité et au calcul du revenu annuel. Guide du concepteur de Modgen v Aperçu de la microsimulation 7

16 Création d un modèle Assistant de création d un nouveau modèle Modgen inclut un assistant de création d un nouveau modèle qui permet de créer la structure d un nouveau modèle de cas. Pour l utiliser, ouvrez d abord Visual Studio 2008 puis choisissez «Nouveau» du menu «Fichier» et «Projet». (Cette version de Modgen nécessite l installation de Microsoft Visual Studio 2008 sur la même machine afin de pouvoir compiler les modèles. Pour plus d information sur l installation et l utilisation de Modgen dans l environnement Visual Studio 2008, référez-vous à l annexe «Modgen et Visual Studio 2008».). Le dialogue «Nouveau projet» suivant apparaît : 8 Création d un modèle Guide du concepteur de Modgen v10.1.0

17 Pour démarrer l assistant de création d un nouveau projet Modgen, sélectionnez «Modgen» comme type de projet (dans la catégorie Visual C++) et soit «Modèle de cas» soit «Modèle basé sur le temps» comme gabarit correspondent. Ensuite, entrez le nom du modèle ou projet, ce qui devient par défaut le nom de la solution créée, puis cliquez sur OK. Le dialogue de bienvenue de l assistant de création d un nouveau modèle apparaîtra, et vous pourrez y préciser le nom de l acteur principal du modèle, la langue de développement du modèle (anglais ou français). Vous pourrez également indiquer si votre modèle sera bilingue ou non. (Pour plus d information sur les acteurs ou les langues du modèle, référezvous au sujet «Éléments du langage Modgen») En cliquant sur «Terminer» dans ce dialogue, la structure du nouveau modèle sera générée, comme le fichier de solution «.sln». Cette solution inclut un autre fichier, «LisezMoi.txt», qui précise le contenu exact de la solution. Guide du concepteur de Modgen v Création d un modèle 9

18 Organisation du code d un modèle dans les fichiers.mpp Pour toute application réussie, il faut organiser le code, les paramètres et les scénarios de modèle. Pour définir le modèle de simulation en langage Modgen, il faut spécifier des acteurs, des paramètres de modèle, des états, des événements, des fonctions auxiliaires C++, des fonctions principales de simulation et un cadre de production de rapports. Tous ces éléments se trouvent dans les fichiers.mpp qui passent en précompilation. Les fichiers.mpp «nom_module.mpp» contiennent toutes les définitions nécessaires de paramètres de modèle, de variables logiques et de classes, ainsi que les éléments de la définition des acteurs et des fonctions d'événement. Le module peut intéresser la démographie, la mortalité, le calcul d'emprunts, la progression scolaire, etc. Il faudra se rappeler que Simulation et CaseSimulation (qui définissent la simulation) devraient aussi figurer dans un de ces modules. Modgen ne restreint pas le nombre de fichiers.mpp traités en précompilation, ni la façon d'organiser les éléments dans ces fichiers. Toutefois, il y a une restriction un fichier mpp ne peut pas avoir le même nom qu'un acteur, paramètre, état, événement, etc. Autrement dit, si, par exemple, l acteur «personne» existe dans un modèle, le fichier «personne.mpp» ne peut pas exister dans le même modèle. En plus, tous les modules d un modèle incluront indirectement un fichier nommé custom.h. Si le concepteur de modèle ne crée pas le fichier custom.h dans le répertoire du modèle, une version de défaut vide est utilisée pendant la compilation C++. Le fichier custom.h est utile pour des modèles contenant des modules C++ programmé directement par le concepteur de modèle, ou dans des modèles incluant des fonctions globales programmé directement par le concepteur de modèle qui doivent être accessibles dans tous les modules du modèle. En particulier, des fichiers bibliothèques personnalisés déclarant des noms globaux définis dans des modules C++ personnalisés devraient être inclus dans le fichier custom.h et non pas dans les fichiers.mpp. En général, tous les modules d un modèle doivent être dans un même répertoire et doivent avoir l extension «mpp». Modgen donc utilisera tous les fichiers avec l extension «mpp» dans ce répertoire de travail. Organisation des paramètres de modèle dans les fichiers.dat Modgen ne limite pas le nombre de fichiers.dat que peut lire son programme d'exécution. Il est donc bon de regrouper les paramètres de modèle liés dans ces fichiers. Règle générale, on a intérêt à créer un fichier.dat renfermant tous les paramètres de modèle se rattachant à une fonction particulière. Ainsi, si les paramètres de modèle se rapportent aux études, on les versera normalement dans un fichier.dat de l'instruction. Le même argument vaut pour les paramètres du revenu. 10 Création d un modèle Guide du concepteur de Modgen v10.1.0

19 Organisation des modèles et des scénarios Il est primordial de travailler avec une copie du modèle dans toute analyse où il faut modifier les fichiers.mpp. C'est agir prudemment, car les erreurs commises n'obligeront pas à réinstaller le modèle à partir du programme d'établissement. L'utilisateur peut aussi comparer les résultats de la version définitive des utilisateurs et de la version diffusée. Modgen traite des entrées et sorties spécifiques de scénarios à l'aide de fichiers de scénario. Tous les fichiers d'entrée (fichiers.dat) et de sortie (.mdb,.xls,.txt) portent le nom du fichier du scénario. Organisation des descriptions et des notes pour les modèles multilingues Modgen accepte les modèles multilingues. On peut donc ajouter une description et une note en Modgen dans n'importe quelle langue, l'information étant compilée dans la version exécutable du modèle et envoyée, si l'utilisateur le demande, dans la base de données de la documentation de Modgen. Les fichiers de la base de données de suivi peuvent aussi recevoir un descripteur dans plus d'une langue, ce qui permet alors de passer de façon dynamique d'une langue à l'autre dans le navigateur Modgen. On peut choisir une ou plusieurs langues en entrant la déclaration suivante des définitions de langue dans un fichier.mpp (de préférence dans le fichier.mpp dans lequel figure l'instruction model_type): Syntaxe : languages { }; langcode, // nom Par exemple : languages { }; langcode // nom EN, // English FR // Français Une étiquette ou une note introduite sans code de langue s'appliquera à la langue par défaut (c'est-à-dire la première langue indiquée dans la déclaration de langue ci-avant). Si on ne fournit pas une étiquette ou une note dans la langue d'exécution choisie, le système utilisera l'étiquette ou la note associée à la langue par défaut. Guide du concepteur de Modgen v Création d un modèle 11

20 Pour plus de renseignements, se reporter aux «Notes relatives aux symboles». Les concepteurs qui souhaitent créer un modèle multilingue peut générer les traductions nécessaires pour les chaînes de caractères internes à Modgen en traduisant soit le contenu du fichier ModgenEN.mpp ou le contenu du fichier ModgenFR.mpp, qui sont tous deux distribués avec Modgen. Pour plus d informations, référez-vous au sujet «Autres Langues». Création d'un fichier exécutable de modèle Il est nécessaire de créer un fichier exécutable de modèle en cas de modification des spécifications de mise en tableau ou du programme du modèle. Un fichier exécutable se crée en deux étapes. D'abord, le programme Modgen.exe convertit les fichiers.mpp en code de modèle C++. Il y a création d'un fichier.cpp correspondant pour chaque fichier.mpp. En seconde étape, on appelle le compilateur C++ et on transforme le code de modèle en fichier exécutable. Avec Modgen 10, les étapes de création de l exécutable d un modèle sont exécutées dans l environnement de Microsoft Visual Studio Des informations détaillées sur l utilisation de Modgen 10 dans cet environnement se trouvent à l annexe «Modgen et l environnement Visual Studio 2008». (Notons également que l exécutable d un modèle Modgen 9 aurait été créé en utilisant Microsoft Visual Studio 2005; les procédures de migration de ces modèles à Modgen 10 sont décrites à la section «Conversion de modèles à Visual Studio 2008» de la même annexe.) Il est également possible de tourner le programme Modgen.exe à l extérieur de l environnement de Microsoft Visual Studio. Les seuls arguments permis sont le répertoire de sortie ainsi que le code de la langue: Modgen.exe [-D répertoire_sortie] -CODELANGUE Le répertoire de sortie est un argument optionnel alors que le code de la langue est obligatoire. Les codes acceptés sont «EN» pour l'anglais et «FR» pour le français. Le texte de sortie sera affiché dans la langue précisée. Comment le code Modgen devient un fichier exécutable de modèle Modgen crée un fichier exécutable pour chaque modification de spécification du modèle. On peut ainsi optimiser la vitesse de simulation des cas. Modgen peut simuler 10 à 100 fois plus de cas que des modèles semblables en langage d'interprétation. Pour atteindre ces vitesses, il convertit en précompilation les commandes Modgen en instructions comprises du compilateur C++. Dans toute spécification, les éléments Modgen et les codes C++ qui spécifient le modèle se trouvent dans un jeu de fichiers.mpp qui passent au précompilateur Modgen.exe. À cette étape de la précompilation, le Modgen.exe transforme les éléments Modgen en instructions et appels de fonctions types C++. Tous les symboles ou éléments déclarés par le 12 Création d un modèle Guide du concepteur de Modgen v10.1.0

21 concepteur dans ces fichiers.mpp sont protégés avec un espace de nommage («namespace») de C++ nommé «mm» (à l origine, «modgen_model»). Cet espace de nommage élimine tout conflit entre les symboles utilisés dans un modèle et des noms utilisés par Modgen ou Microsoft. Toutefois, à noter que les déclarations dans custom.h sont globales, c.-à-d. qu elles ne se trouvent pas par défaut dans cet espace de nommage. Pour inclure une déclaration dans l espace de nommage «mm», tu dois la mettre dans une commande «namespace mm {}». On obtient ainsi un ensemble de fichiers.cpp et un ensemble de fichiers spéciaux ACTORS.H, ACTORS.cpp, TABINIT.H, TABINIT.cpp, MODEL.H, MODEL.RC et PARSE.INF. Une version vierge du fichier «custom.h» est également générée si le concepteur n a pas créé un tel fichier spécialement pour le modèle. Ces fichiers et un ensemble de bibliothèques C++ et de bibliothèques spéciales Modgen passent ensuite au compilateur C++ en vue de la création du fichier exécutable de l'application. Tous les fichiers.cpp et le fichier MODEL.RC doivent être ajoutés aux fichiers du projet pour que la compilation réussisse. On peut aussi intégrer tous les fichiers.mpp et.dat dans le projet, bien que ce ne soit pas essentiel à la compilation. Le schéma suivant illustre les liens entre les fichiers nécessaires à la création d'un fichier exécutable de modèle de simulation dans le cadre de l'application. Il présente aussi les entrées et les sorties dont a besoin le fichier exécutable du modèle. fichiers.cpp fichiers mpp modgen.exe ACTORS.H ACTORS.CPP TABINIT.H TABINIT.CPP MODEL.H MODEL.RC PARSE.INF Compilateur C++ fichiers sce et dat fichier exe BIBLIOTHÈQUE Tableaux Avis de droit d'auteur Comme concepteur de modèle, vous pouvez ajouter un avis de droit d auteur à votre modèle dans chaque langue connue du modèle. Modgen permet cet avis par l entremise d une chaîne de caractère «S_COPYRIGHT1» dont le contenu peut Guide du concepteur de Modgen v Création d un modèle 13

22 être precise dans l un des modules du modèle. Deux lignes de texte sont permises pour chaque avis, et «\n» est permis comme délimiteur de ligne, comme vous pouvez le remarquer dans l exemple suivant qui montre la définition de l avis en français ainsi qu en anglais. string S_COPYRIGHT1; //FR LifePaths est une publication autorisée par le ministre responsable de Statistique Canada.\n Ministre de l'industrie. string S_COPYRIGHT1; //EN LifePaths published by authority of the Minister responsible for Statistics Canada.\n Minister of Industry. Création d'un icone personnalisé pour un modèle Modgen distribue le fichier APP.ICO qui est copié dans le répertoire du modèle (s'il ne s'y trouve pas déjà) lors de l'exécution de Modgen. Pour créer un icone personnalisé, modifiez simplement le fichier APP.ICO. Notez que l'icone n'est pas affiché dans la vue de ressource du projet; de fait, aucunes des ressources internes de Modgen ne sont affichées à l'intention du concepteur du modèle). Après avoir modifié le fichier APP.ICO, on doit relancer Modgen. Précisons que chaque exécution de Modgen entraîne une recompilation des ressources ainsi qu'une redéfinition des liens du modèle. 14 Création d un modèle Guide du concepteur de Modgen v10.1.0

23 Exécution d'une simulation du modèle Exécution du fichier exécutable du modèle Dès qu'il est exécuté, un modèle Modgen présente à l'utilisateur une interface visuelle générique qui lui permet de modifier la configuration, de fixer les paramètres de contrôle de simulation, d'exécuter les simulations et de visualiser les sorties de la simulation. Pour plus de renseignements sur l'exécution du fichier exécutable du modèle, référez-vous au «Guide de l interface visuelle de Modgen» ; cependant, on présente ici une brève description pour les concepteurs. Pour l'instant, les concepteurs doivent fournir avec les modèles un ensemble initial de fichiers.dat qui sont nécessaires à l'exécution du modèle. Cet ensemble initial est souvent désigné comme les valeurs de base du cas, c'est-à-dire simplement les valeurs par défaut choisies par le concepteur pour les utilisateurs du modèle. La version exécutable compilée d'un modèle ne lancera pas une simulation s'il n'existe pas un scénario sauvegardé (fichier avec extension.sce). Un fichier de scénario Modgen est un fichier texte de type.ini qui renferme les paramètres de contrôle de simulation nécessaires à l'exécution d'une simulation. Il y a deux façons d'exécuter une simulation pour un modèle. On peut d'abord, à partir de l'interface visuelle, lancer l'exécutable à partir d'explorer (ou de Start/Run) sans invoquer aucun argument, ou en utilisant un fichier de scénario précédemment sauvegardé. À ce moment-là, on choisit Exécuter au menu Scénario. Pour spécifier les options de la simulation, on recourra à la fenêtre de dialogue Ligne de commande. On peut aussi lancer le modèle directement à la ligne de commande d'une fenêtre DOS en tapant l'argument sc à la suite du nom du fichier du scénario. Le modèle peut également être lancé en mode de documentation seule (voir la syntaxe 3 ci-après). Syntaxe1 : Appel de l'interface visuelle du modèle nom_modèleexe <nom fichier_scénario> Guide du concepteur de Modgen v Exécution d'une simulation du modèle 15

24 aucun autre argument n'est accepté. s'il n'y a aucun argument, l'interface visuelle apparaîtra sans ouvrir de scénario. Cette option est particulièrement utile lorsqu'on désire lancer le modèle simplement en cliquant deux fois sur le nom du fichier dans Explorer. utiliser Scénario/Exécuter pour lancer la simulation. Syntaxe2 : Lancement du modèle en vue d'une exécution par lots Exécute le modèle à l'aide des paramètres de contrôle d'exécution pris dans le fichier du scénario et présente une ligne de commande qui sert à préciser la priorité des calculs. Sous ce mode, la simulation débute en mode minimal. nom_modèleexe sc nom_fichier_scénario <-priorité_calcul> la priorité de calcul est facultative et elle peut être normale, faible ou élevée; aucun autre argument n'est accepté. Syntaxe3 : Lancement du modèle en mode de documentation seule Cette syntaxe crée la base de données de la documentation décrite dans la section «Contenu de la base de données de la documentation Modgen». Aucune interface utilisateur n'est affichée pendant que le modèle s'exécute en mode de documentation seule. nom_modèleexe -doc <nom_fichier> <-s> (par exemple lpaths -doc MonDoc.mdb) <> désigne un argument facultatif. Si le «nom_fichier» n'est pas précisé, le nom de la base de données de la documentation sera : modèleexe(doc).mdb (par exemple lpaths(doc).mdb ). Si le «nom_fichier» est indiqué sans suffixe, «.mdb» est ajouté. L'exécution ne demande normalement au plus quelques secondes. Puis, une boîte de message s'affiche indiquant si l'opération a réussi ou échoué. Vous pouvez annuler l'affichage de cette boîte en entrant l'option «-s» (mode silencieux). Initialisation des valeurs de paramètres de modèle dans les fichiers.dat Les valeurs des paramètres de modèle sont stockées dans les fichiers.dat. L'interface visuelle nommera les fichiers.dat selon le nom du scénario, de la façon suivante : nom_scénario (nom_fichier).dat. Le rang et la forme du paramètre ainsi que la signification de chacune de ses dimensions, le cas échéant, doivent être définis à la fois dans le fichier.mpp et dans le fichier.dat. La taille du paramètre de modèle se présente typiquement en classifications ou fourchettes. Les valeurs des paramètres doivent s'exprimer de la façon suivante : 16 Exécution d'une simulation du modèle Guide du concepteur de Modgen v10.1.0

25 Syntaxe d'initialisation des paramètres de modèle dans les fichiers.dat parameters { type name[size_dim1]...[size_dimn] = { value, value,..., value } ou }; type name[size_dim1]...[size_dimn] = ( repeater) { value, value,..., value } Les répéteurs peuvent être imbriqués dans les blocs des valeurs de données. Quel que soit le nombre de dimensions de paramètre, les valeurs des paramètres sont toujours introduites sous forme de vecteurs par ordre le plus élevé de la ligne (c.-à-d. avec les valeurs des dimensions les plus faibles, les colonnes, changeant le plus rapidement, et les dimensions de rang supérieur qui changent le moins vite). On introduit chaque valeur en passant en premier lieu par les valeurs de dimensions les moins significatives. Dès que ces valeurs ont été utilisées, on passe aux valeurs moins significatives suivantes et le phénomène se répète jusqu'à ce que toutes les valeurs aient été prises en compte. Par exemple, supposons que votre paramètre comporte deux dimensions (de rang 2), qu'il ait la forme 2 sur 3 et qu'il renferme les valeurs suivantes : votre déclaration dans le fichier.dat ressemblerait alors à ce qui suit : param[dim1_2values][dim2_3values] = { 3, 4, 5, 7, 8, 9}; Exemple 1 Les virgules terminales sont permises (sans être exigées) en initialisation de paramètre. Les deux exemples suivants conviennent donc : param[dimension] = { 1, 2, 3 }; param[dimension] = { 1, 2, 3, }; Exemple 2 Les initialisateurs de paramètre peuvent maintenant contenir des tranches numériques répétées qui peuvent aussi s'imbriquer. param[dim] = { (15) 0, 1, 2, 3, 4 }; Guide du concepteur de Modgen v Exécution d'une simulation du modèle 17

26 param[dim] = { 0, (2) { 1, 2, (3) { 3, 4 }, 5, 6 }, } Le second exemple équivaut à : }; param[dim] = { 0, 1, 2, 3, 4, 3, 4, 3, 4, 5, 6, 1, 2, 3, 4, 3, 4, 3, 4, 5, 6 La méthode la plus simple pour modifier la valeur d'un paramètre dans un modèle est d'utiliser l'interface visuelle. Cependant, si le paramètre se compose d'un nombre (scalaire) ou d'un court vecteur de nombres, on peut modifier directement ce nombre dans le fichier.dat à l'aide d'un éditeur de texte. On ne devrait pas modifier la définition du paramètre dans un fichier.dat lorsqu'on change une valeur paramétrique. Exemple Dans cet exemple, nous modifions la valeur du paramètre scalaire FemaleProp de 0,5 à 1,00 pour que la simulation ne porte que sur les femmes. Les lignes suivantes du fichier person.dat // spécification du paramètre parameters { float FemaleProp = 0.5; }; deviennent // spécification du paramètre parameters { float FemaleProp = 1.0; }; Il n'est pas recommandé de modifier directement un fichier.dat à l'aide d'un éditeur de texte pour changer une fourchette de valeurs de paramètres de modèle pour une matrice dimensionnelle de plus haut niveau. En effet, lorsque la dimensionnalité est supprimée, on peut difficilement savoir quel élément du paramètre est modifié. Ces valeurs proviennent d'ordinaire d'un fichier externe et collées, par exemple, à partir d'un chiffrier. Il est donc préférable de créer ces valeurs dans la syntaxe du fichier.dat ou de les remettre à zéro puis d'utiliser par la suite l'éditeur 18 Exécution d'une simulation du modèle Guide du concepteur de Modgen v10.1.0

27 visuel. Fichiers de sortie des modèles Modgen Modgen produit les sorties du modèle en leur donnant le nom du scénario suivi d'un identificateur entre crochets qui indique le type de sortie Modgen, et d'une extension indiquant le type de fichier. Les fichiers peuvent être groupés en trois catégories : Tableaux présentant les résultats agrégatifs du modèle : nom_scénario(tbl).mdb sortie MS Access (elle est toujours produite lorsque le modèle est exécuté et utilisé par l'interface visuelle pour visualiser un tableau). nom_scénario(tbl).xls tableaux de sortie Excel. Il s'agit du nom par défaut utilisé par la fonction d'exportation de tableau. Pour créer ce fichier, faites appel à l'option de menu Scénario/Exporter tableau depuis l'interface visuelle. Plusieurs formats sont offerts pour ce type de sortie. nom_scénario(tbl).txt tableaux de sortie en format texte. Il s'agit du nom par défaut utilisé par la fonction d'exportation de tableau. Pour créer ce fichier, faites appel à l'option de menu Scénario/Exporter tableau depuis l'interface visuelle. Sorties de suivi pour l'examen d'une vie individuelle : nom_scénario(trk).mdb sortie de suivi en MS Access utilisée par le BioBrowser de Modgen. Ce fichier n'est produit que si l'utilisateur le sélectionne à la boîte de dialogue Ligne de commande. nom_scénario(trk).txt sortie de suivi en format texte. Ce fichier n'est produit que si l'utilisateur le sélectionne à la boîte de dialogue Ligne de commande Fichiers de journalisation et d'erreurs : nom_scénario(log).txt fichier de journalisation de Modgen (ce fichier est toujours produit; si des erreurs surviennent, il comprend également les messages d'erreur). nom_scénario(err).txt fichier d'erreurs de Modgen (ce fichier n'est produit que s'il y a des problèmes à la lecture des fichiers d'entrée). scenario_name(trc).txt fichier de Modgen avec beaucoup d autres informations dans les cas ou le modèle plante (le fichier est détruit automatiquement si le modèle réussit à quitter correctement) Pour plus de renseignements sur ces fichiers, on voudra bien se reporter au Guide de l interface visuelle de Modgen. Guide du concepteur de Modgen v Exécution d'une simulation du modèle 19

28 Éléments du langage Modgen Aperçu des éléments de Modgen Dans cette section, nous décrivons les éléments du langage Modgen qui n'appartiennent pas au langage standard C++ et qui facilitent grandement la représentation d'un modèle de microsimulation dans un cadre de programmation structurée. On doit définir presque tous les éléments Modgen avant leur mise en code de simulation. Ainsi, cette définition non seulement assure une bonne compilation du modèle, mais constitue aussi un document de référence sur l'agencement fonctionnel des éléments. Définition de la nature du modèle de microsimulation Le premier élément essentiel que doit définir le concepteur d'applications est le type de modèle à construire. Le modélisateur définit le type du modèle à l'aide de l'une des instructions suivantes (endroit recommandé : début du fichier main.mpp) : model_type case_based<,just-in-time>; model_type time_based<,just-in-time>; model_type cell_based; L'interface visuelle varie selon le type du modèle. Pour plus de renseignements, reportez-vous au Guide de l interface visuelle de Modgen. Le mot-clé just_in_time est optionel et a des conséquences sur l avancement du temps lorsqu un événement survient. Pour plus de renseignements, reportez-vous à la section «Événements», trouvée ailleurs dans ce Guide. Pour les modèles de cas, on doit se servir de l'instruction time_type pour indiquer si le modèle est discret ou continu. L'instruction time_type, que l'on trouve généralement dans le fichier.mpp contenant toutes les définitions du modèle, peut utiliser char, short, int, long, uchar, ushort, uint, ou ulong pour les modèles temporels discrets et peut utiliser double ou float pour les modèles continus. (Les types uchar, ushort, uint, et ulong sont des synonymes pour les types 20 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

29 C++ unsigned char, unsigned short, unsigned int, et unsigned long). Modgen donne double par défaut pour l élément time_type si rien n'est spécifié. Pour les modèles temporels, l'instruction time_type doit préciser double. Modgen définit l'état de l'âge par cette définition. L'utilisateur n'a à spécifier cette variable pour aucune des définitions d'acteurs, bien qu'aucun modèle de microsimulation ne soit complet sans cette indication. Il y a création automatique de cette variable par le système. Modgen définit aussi le type TIME par cette définition. Cet élément sert souvent à définir les variables étroitement liées au concept temporel de l'application. Exemple // On définit le type temporel pour le modèle de l'exemple simple. // Comme il s'agit d'un modèle annuel, donc d'un modèle temporel discret, // le type de modèle est int time_type int; S'il s'agit d'un modèle temporel continu, indiquez : time_type double; ou time_type float; À la différence des autres types de modèle, on estime que le modèle de cellule figure au stade de simulation durant le traitement des tableaux d'utilisateur (par la fonction UserTables). La mise à jour du déroulement est effectuée (dans la simulation ou dans la fonction UserTables) par le lancement de la fonction suivante de Modgen : void CalculationProgress(double dpctdone); Définition des acteurs Dans la définition de l'acteur, on énumère toutes les états, les événements et les fonctions auxiliaires qui intéressent cet acteur. Comme nous l'avons déjà mentionné, la variable de l'âge n'a pas à être spécifiée par l'utilisateur dans cette définition puisque Modgen l'indique automatiquement. Bien que la définition de l'acteur comprenne tous les événements et les fonctions auxiliaires, le code source de ces modules, où l'on peut exploiter tous les éléments de C++, n'est pas contenu dans cette définition. Voici la syntaxe de cette dernière : Syntaxe actor name // étiquette Guide du concepteur de Modgen v Éléments du langage Modgen 21

30 { type variable; // nom de la variable (moulage simple) type variable[class]; // nom de variable matricielle (moulage simple) type variable = identity_expression; // nom de variable (expression d'identité) type variable = {value}; // nom de variable (initialisateur d'état) type variable = supporting_function() // nom de variable (par une fonction C++) type variable = MACRO() // nom de variable (par une macro-instruction C++) event function // fonction d'événement liée à l'acteur function_prototype // fonctions C++ appelées par des événements ou par le moteur de simulation } Pour plus de renseignements sur les événements et les fonctions auxiliaires, se reporter aux «Sujets avancés en Modgen». Dans notre exemple simple, il n'y a qu'un acteur personne. Le modèle simule l'état d'invalidité de l'intéressé pendant sa vie. Comme nous sommes renseignés par un paramètre de modèle sur les transitions entre états d'invalidité selon l'âge et le sexe, il nous faut aussi définir une variable décrivant l'âge, le sexe et l'état d'invalidité de cette même personne. Modgen indique automatiquement la variable de l'âge, aussi celle-ci n'entre-t-elle pas dans la définition suivante de l'acteur. // définition de l'acteur personne // dans le modèle d'exemple simple, il n'y a qu'un événement pour l'acteur // personne qui se produit une fois l'an afin de calculer le revenu annuel // d'invalidité de la personne et son revenu annuel correspondant à condition // que cette personne soit toujours en vie. // On appelle cet événement AgeOneYearEvent. // Pour estimer le temps d'attente avant l'exécution de cet événement, // nous employons la fonction timeageoneyearevent. actor Person // Définition de l'acteur personne 22 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

31 { // états nécessaires à cette simulation // nota : Modgen indique automatiquement la variable d'âge SEX sex; // Sexe int earnings = {0} ; // Gains accumulés pendant la vie // jusqu'ici DFLE_STATE dfle = {NO_DIS}; // État des DFLE LIFE_STATE life_status = {ALIVE}; // État de la vie // états nécessaires aux rapports de totalisation int person_year = duration (life_status,alive); // Années-personnes int int age_at_death = value_at_changes ( life_status, age ); // Âge au décès death = value_at_entrances ( life_status, NOT_ALIVE, age ); // Âge //au décès // fonctions appelées par la fonction d'événement Dwelling event timeageoneyearevent, AgeOneYearEvent; // fonctions dont a besoin le moteur de simulation void Start(); void Finish(); }; Valeurs des arguments implicites pour les prototypes de fonction d'acteur Modgen soutient les valeurs d'arguments implicites pour les fonctions d'acteur. Les fonctions déclarées à l'aide de valeurs d'arguments implicites peuvent être appelées à l'aide d'un nombre moins élevé d'arguments que ne l'exige le prototype de la fonction. Guide du concepteur de Modgen v Éléments du langage Modgen 23

32 Exemple actor Person { void Start( logical btentative, logical dom, TIME birth = TIME_INFINITE, TIME immig = TIME_INFINITE, SEX esex = MALE, PROVINCE eprov = ONT ); }; prdominant->start( FALSE, TRUE ); // valeurs implicites utilisées pour les // quatre autres arguments Ensembles d acteurs Les acteurs peuvent aussi être membres d ensembles d acteurs. Un ensemble d acteurs est une collection d acteurs maintenue dynamiquement par Modgen. «Maintenue dynamiquement» signifie que Modgen s occupe de l adhésion au groupe selon le critère fourni par le concepteur de modèle. Les ensembles d acteurs peuvent être utiles pour les modèles de temps avec plusieurs acteurs ayant des interactions. Les ensembles d acteurs ont été créés pour faciliter le développement de ces modèles en éliminant la nécessité pour le concepteur d écrire du code pour maintenir et manipuler de tels ensembles. Par exemple, Modgen fournit des fonctions que le concepteur de modèle utilise pour sélectionner aléatoirement un acteur de l ensemble, pour itérer sur tous les membres d un ensemble, etc. Pour plus de renseignements, reportez-vous à la section «Ensembles d acteurs», trouvée dans le chapitre «Sujets avancés en Modgen» de ce Guide. Définition des états Les états décrivent toutes les caractéristiques de l'acteur. Dans C++, ce sont des membres de données des objets acteurs. On doit déclarer des états dans la définition d'acteur de chaque objet acteur. Les états sont toujours des valeurs scalaires et doivent être indiquées comme une variable int, long, float, double ou l'un des types particuliers de Modgen : TIME, logical, classification ou range. On affecte les valeurs des états par évaluation d'une expression d'identité dans la définition de l'acteur ou de l'expression C++ dans un événement ou une fonction auxiliaire C++ appelée par un 24 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

33 événement. Les états se définissent par «moulage» simple (cast), initialisateur d'état, expression d'identité, appel d'une fonction auxiliaire ou expression de macro-instruction en C++. Les états devraient toujours être initialisés en utilisant des accolades. Si des accolades ne sont pas utilisées, alors ça signifie que l état est un état d expression pour lequel la valeur est maintenue en tout temps par Modgen. Si votre modèle contient un état d'expression qui est modifié dans le code, Modgen affichera un avertissement lors de la simulation indiquant que l'assignation d'une valeur à cet état a été ignorée. L'expression d'identité peut contenir une simple affectation, une définition arithmétique, une opération booléenne en C++, un opérateur d'expression conditionnelle (?:) dans ce même langage ou le résultat d'une fonction spéciale Modgen. Modgen actualise automatiquement la valeur de chaque variable chaque fois qu'une fonction auxiliaire modifie une variable qui la conditionne au cours de la vie en simulation. Il faut bien souligner que la définition de l'acteur peut déclarer tout autre genre de variable (p. ex., des valeurs matricielles multidimensionnelles), cependant Modgen ne les considérera pas comme un état, car ces déclarations deviennent un simple membre de données de la classe d'objet. Définition des états de Modgen Modgen crée les états spéciales suivantes pour chaque acteur : actor_id L état «actor_id» est un identificateur unique pour un acteur, généré par Modgen pour chaque acteur dans le modèle. L état peut être utilisé dans le code du modèle mais il ne peut pas être modifié. Note que «actor_id» identifie chaque acteur dans une simulation, mais il ne devrait pas être utilisé comme identificateur pour comparer des acteurs de différentes simulations. Sa valeur n est unique qu à l intérieur d une simulation particulière. actor_subsample_weight L'état actor_subsample_weight équivaut à la valeur actor_weight multipliée par le nombre de sous-échantillons. Cet état précise le poids utilisé pour les quantités de sous-échantillons (la valeur actor_weight est employée pour les quantités totales). L'état «actor_subsample_weight» peut être déterminé et affiché à l'aide du BioBrowser. actor_weight Un état spécial, appelé «actor_weight» est offert pour chaque acteur. L'appel de la fonction SetCaseWeight entraîne la définition de la valeur «actor_weight» pour chaque acteur du cas. L'état «actor_weight» peut être déterminé et affiché à l'aide du BioBrowser. age L'état age indique l'âge de l'acteur et se définit par le type TIME qui dépend du type time_type dans le modèle. Cette variable peut uniquement être établie dans la fonction type de l'acteur, sinon elle sera initialisée à zéro. Par la suite, on ne pourra y faire appel que dans le code du modèle. Guide du concepteur de Modgen v Éléments du langage Modgen 25

34 case_id L'état case_id contient un identificateur unique pour chaque cas et est du type long. Pour ce qui est des modèles de cas, cet état indique le numéro courant du cas (origine 1). Elle n'est pas utilisée dans les modèles temporels. La variable case_id fait toujours l'objet d'un suivi dans tous les modèles de cas. Elle ne peut donc être établie que par renvoi au code du modèle. case_seed La variable case_seed indique la valeur de départ du cas en cours de traitement et est du type double. À remarquer qu'on utilise pour chaque échantillon deux générateurs de nombres aléatoires, le premier pour générer la valeur de départ de chaque cas, l'autre pour générer le flot de nombres aléatoires pour la simulation. Cette façon de faire rend l'exécution des modèles plus cohérente étant donné qu'un appel supplémentaire au générateur de nombres aléatoires dans un cas n'affectera pas la valeur de départ du cas suivant. Elle ne peut jamais être établie, mais seulement par renvoi au code du modèle. time L état time indique le temps courant et est du type time. Cette variable sert également au suivi des états dans le cadre du programme de débogage du modèle. Cette variable peut uniquement être établie dans la fonction type de l'acteur, sinon elle sera initialisée à zéro. Par la suite, on ne pourra y faire appel que dans le code du modèle. Aussi, Modgen génère automatiquement des étiquettes pour ces états, en français et en anglais, comme dans le tableau suivant : Étiquette française Étiquette anglaise actor_id Identificateur d acteur Actor identifier case_id Identificateur de cas Case identifier case_seed Valeur aléatoire d amorçage de cas Case random seed time Temps Time age Âge Age actor_weight Poids Weight actor_subsample_weight Poids du sous-échantillon Sub-weight Définition des états d'un modèle 26 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

35 La définition de l'acteur peut déclarer diverses états qui doivent être des valeurs scalaires. Les états numériques en Modgen peuvent être déclarés comme un type standard de C++, c'est-à-dire int, long, float ou double. Les types char et short pourraient être utilisés pour des petites valeurs intègres signées. Aussi, les types uchar, ushort, uint, et ulong pourraient être utilisés pour des valeurs intègres sans signe. (Le type uchar est un synonyme en un mot de Modgen du type C++ «unsigned char», le type ushort est un synonyme du type C++ «unsigned short», etc.) Modgen autorise les déclarations à l'égard des états suivantes du type : classification Les états catégoriques sont définis au moyen d'une classification. Les états définis d après une classification ne peuvent être initialisés qu au moyen d une valeur provenant de la classification appropriée. L utilisation de toute autre valeur produira une erreur de compilation C++ en rapport avec la ligne du fichier source mpp où l état de type classification est défini et initialisé. La déclaration du type renferme le nom de la classification, comme l'exemple ci-après l'illustre. Exemple // L état gender est déclaré à l'aide de la classification SEX SEX gender; // le sexe logical Les états booléennes entrant dans la définition de l'acteur se définissent selon le type logical. Les valeurs d'état logiques sont FALSE (valeur nulle) et TRUE (valeur non nulle). Exemple // La variable resident est vraie lorsque l'âge de l'acteur est supérieur à son âge // au moment de l'immigration logical resident = age >= age_imm; range Les états dont les valeurs sont définies par un intervalle numérique quelconque se caractérisent par une fourchette (range). Exemple range LIFE { 0, 99 }; // durée de la vie real, counter, et integer Ces trois types peuvent être utilisés pour déclarer des états d acteurs contenant des valeurs à virgule flottante (real), des valeurs intègres non négatives (counter) ou des valeurs intègres (integer). Les types C++ vraiment utilisés par le modèle Guide du concepteur de Modgen v Éléments du langage Modgen 27

36 sont contrôlés par les commandes real_type, counter_type, et integer_type, respectivement. Ces types et ces commandes pourraient être utiles dans des modèles où la mémoire est importante, comme des modèles «time-based» ayant beaucoup d'acteurs. Pour de tels modèles, des concepteurs pourraient considérer déclarer tout état de virgule flottante comme real, des états non négatifs comme counter, et des états intègres comme integer. Les commandes real_type, counter_type, ou integer_type pourraient par la suite réduire l'utilisation de mémoire. Le tableau suivant indique les caractéristiques de chacun de ces trios types : type real type counter type integer Types C++ permis dans float (utilise 4 octets de mémoire, char ou uchar (1 octet) char (1 octet) l énoncé (avec la mémoire utilisée par chaque type) contient 6 chiffres de précision) double (utilise 8 octets de mémoire, contient 15 chiffres de précision) short ou ushort (2 octets) int ou uint (4 octets) long ou ulong (4 octets) short (2 octets) int (4 octets) long (4 octets) Type C++ utilisé par double int int défaut si le modèle ne contient pas d énoncé pour le type Exemples d énoncés de type et de déclarations d états real_type float; actor Person { real earnings; }; counter_type ushort; actor Person { counter jobs; }; integer_type short; actor Person { integer gains_and_losses; }; Commentaires sur Utiliser double pour maximiser la Le concepteur de modèle Le concepteur de modèle est l utilisation optimale précision ou float pour minimiser est responsable d assurer responsable d assurer que la par les concepteurs de l utilisation de mémoire que la valeur d un état valeur d un état integer ne modèle counter ne dépasse pas les dépasse pas les bornes du type bornes du type C++ donné C++ donné dans la commande dans la commande integer_type counter_type 28 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

37 TIME Le type TIME a aussi un sens particulier en Modgen. Il tire sa valeur du time_type, c'est-à-dire du moulage qui fixe le type de modèle de simulation. Les états liées au concept temporel du modèle sont définis avec le type TIME. Expressions d'état dérivées utilisées dans les définitions d'acteurs et de tableaux Modgen prévoit divers états dérivés spéciaux qui enregistrent les valeurs des états à tout stade de la simulation. Ces états spéciaux servent à la production de rapports et aux affectations d'états dans les expressions Modgen. Les arguments peuvent être une variable de classification ou de fourchette ou une variable ordinaire du type int ou long. L'argument d'état qui y est associé doit être du type correspondant. Exemples undergone_entrance (dfle, SEVERE_DIS) undergone_entrance (children, 1) États dérivés associés aux changements d'état des acteurs Liste par ordre alphabétique : changes(variable) Nombre de fois que la variable classification a changé jusqu'ici dans la simulation. Ainsi, la fonction changes (dfle) donne le nombre de fois que l'état d'invalidité a changé. Prenons le cas de quelqu'un qui a vécu jusqu'à l'âge de 77 ans et dont l'état d'invalidité a changé tous les 10 ans depuis l'âge de 15 ans. La valeur de la variable changes serait de 0 avant l'âge de 15 ans, de 1 avant l'âge de 25 ans, de 2 avant l'âge de 35 ans, etc. À l'âge du décès, elle serait de 7. entrances(variable, état) Il s'agit du nombre de fois que la variable est entrée dans l'état en question jusqu'ici dans la simulation. Ainsi, la fonction entrances (dfle, SEVERE_DIS) enregistre le nombre de fois que l'intéressé est entré dans un état d'invalidité grave jusqu'ici dans la simulation. Si quelqu'un a vécu jusqu'à l'âge de 75 ans et est entré dans un tel état à 25 et à 60 ans, la valeur sera de 0 avant l'âge de 25 ans, de 1 avant l'âge de 60 ans et de 2 pour le reste de la vie. Guide du concepteur de Modgen v Éléments du langage Modgen 29

38 exits(variable, état ) Il s'agit du nombre de fois que la variable est sortie de l'état en question jusqu'ici dans la vie en simulation. Ainsi, la fonction exits (dfle, SEVERE_DIS) donne le nombre de fois que quelqu'un est sorti d'un état d'invalidité grave jusqu'ici dans la simulation. S'il a vécu jusqu'à l'âge de 75 ans, est devenu gravement handicapé à 25 et à 60 ans et est sorti de cet état d'invalidité à 31 ans, la valeur sera de 0 jusqu'à l'âge de 31 ans et de 1 pour le reste de la vie. transitions(variable, passage d'un certain état à un certain état ) Il s'agit du nombre de fois que l'intéressé est passé de l'état d'origine à l'état de destination jusqu'ici dans la vie en simulation. Ainsi, la fonction transitions (dfle, MILD_DIS, MEDIUM_DIS) indique le nombre de fois que l'intéressé est passé de l'état d'invalidité légère à l'état d'invalidité moyenne jusqu'ici dans la simulation. undergone_change(variable ) La valeur de cette fonction est de 1 si la variable a changé d'état jusqu'ici dans la simulation et de 0 dans les autres cas. Prenons le cas d'une personne qui a vécu jusqu'à l'âge de 75 ans et est devenue invalide à 68 ans. La valeur de la variable undergone_change (dfle) est de 0 avant l'âge de 68 ans et de 1 pour le reste de la vie. undergone_entrance(variable, état ) La valeur de cette fonction est de 1 si la variable est entrée dans l'état en question jusqu'ici dans la simulation et de 0 dans les autres cas. Prenons le cas de quelqu'un qui a vécu jusqu'à l'âge de 75 ans et est devenu gravement handicapé à 68 ans. La valeur de undergone_entrance(dfle, SEVERE_DIS) est donc de 0 jusqu'à l'âge de 68 ans et de 1 pour le reste de la vie. value_at_changes (variable, variable enregistrée ) Il s'agit de la somme des valeurs de la variable enregistrée aux divers changements. Avec la fonction changes, cette fonction permet de calculer la valeur moyenne d'une variable enregistrée au fil des changements intervenus jusqu'ici dans une simulation. Ainsi, la value_at_changes (dfle, age) donne la somme des âges où l'état d'invalidité a changé. Si quelqu'un a vécu jusqu'à l'âge de 77 ans et que son état d'invalidité a changé tous les 10 ans depuis l'âge de 15 ans, la valeur de la fonction à l'âge du décès sera de = 260. L'âge moyen sera le quotient de ce résultat et du nombre de changements, soit : 260/7=37.1 value_at_entrances (variable, état, variable enregistrée) Il s'agit de la somme des valeurs de la variable enregistrée aux entrées dans l'état en question. Avec la fonction entrances, cette fonction sert à calculer la valeur moyenne d'une variable enregistrée pour les entrées dans un état quelconque pendant la vie en simulation. Ainsi, la value_at_entrances (dfle, SEVERE_DIS, age) donne la somme des âges où l'intéressé est entré dans un état d'invalidité grave. Si l'intéressé a vécu jusqu'à l'âge de 75 ans et est devenu gravement handicapé à 25 et à 60 ans, cette fonction a une valeur de 0 jusqu'à l'âge de 25 ans, de 25 jusqu'à l'âge de 60 ans et de 85 jusqu'à l'âge du décès. 30 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

39 value_at_exits (variable, état, variable enregistrée ) Il s'agit de la somme des valeurs de la variable enregistrée aux sorties de l'état en question. Avec la variable exits, cette fonction sert à calculer la valeur moyenne d'une variable enregistrée aux sorties d'un état quelconque pendant la vie en simulation. Ainsi, la value_at_exits (dfle, SEVERE_DIS, age) donne la somme des âges de sortie de l'état en question. Si quelqu'un a vécu jusqu'à l'âge de 75 ans, est devenu gravement handicapé à 25 et à 60 ans et est sorti de l'invalidité à 31 ans, la valeur de la fonction est de 0 jusqu'à l'âge de 31 ans et de 31 jusqu'à l'âge du décès. value_at_first_change(variable, variable enregistrée ) Il s'agit de la valeur de la variable enregistrée lorsque l'état a changé la première fois. Si la variable n'a pas encore changé d'état jusqu'ici dans la vie de l'intéressé, la fonction a une valeur nulle. Ainsi, la value_at_first_change (dfle, age) donne l'âge de quelqu'un au premier changement d'état d'invalidité. Si l'intéressé a vécu jusqu'à l'âge de 70 ans et que son état d'invalidité a changé à 25 et à 60 ans, la valeur est de 0 avant l'âge de 25 ans et de 25 pour le reste de la vie. value_at_first_entrance(variable, état, variable enregistrée ) Il s'agit de la valeur de la variable enregistrée à la première entrée dans l'état en question. Si l'intéressé n'est pas encore entré dans cet état jusqu'ici dans sa vie, la fonction présente une valeur nulle. Ainsi, la value_at_first_entrance (dfle, SEVERE_DIS, age) enregistre l'âge de quelqu'un lorsqu'il est entré la première fois dans un état d'invalidité grave. Si l'intéressé a vécu jusqu'à l'âge de 70 ans et est devenu gravement handicapé à 25 et à 60 ans, la valeur est de 0 avant l'âge de 25 ans et de 25 pour le reste de la vie. value_at_transitions (variable, passage d'un certain état à un certain état, variable enregistrée ) Il s'agit de la somme des valeurs de la variable enregistrée aux passages de l'état d'origine à l'état de destination. Avec la fonction transitions, cette fonction sert à calculer la valeur moyenne de la variable pour les transitions en question jusqu'ici dans la vie en simulation. Ainsi, la value_at_transitions (dfle, MILD_DIS, MEDIUM_DIS, age) donne la somme des âges de passage de l'état d'invalidité légère à l'état d'invalidité grave. value_at_latest_change(variable, variable enregistrée ) Il s'agit de la valeur de la variable enregistrée au dernier changement. Si la variable de classification n'a jamais changé d'état, la valeur de la fonction est nulle. Ainsi, la value_at_latest_change (dfle, age) donne l'âge de quelqu'un au dernier changement d'état d'invalidité. Si l'intéressé a vécu jusqu'à l'âge de 75 ans et que son état d'invalidité a changé à 25 et à 60 ans, la valeur est de 0 jusqu'à l'âge de 25 ans, de 25 jusqu'à l'âge de 60 ans et de 60 jusqu'à l'âge du décès. value_at_latest_entrance(variable, état, variable enregistrée ) Il s'agit de la valeur de la variable enregistrée à la dernière entrée dans l'état en question. Si l'intéressé n'est jamais entré dans cet état (variable de classification), la fonction présente une valeur nulle. Guide du concepteur de Modgen v Éléments du langage Modgen 31

40 Ainsi, la value_at_latest_entrance (dfle, SEVERE_DIS, age) donne l'âge à la dernière entrée dans un état d'invalidité grave. Si quelqu'un a vécu jusqu'à l'âge de 75 ans et est devenu gravement handicapé à 25 et à 60 ans, la fonction a une valeur de 0 jusqu'à l'âge de 25 ans, de 25 jusqu'à l'âge de 60 ans et de 60 jusqu'à l'âge du décès. États dérivés associés à la durée des états des acteurs Les fonctions suivantes somment les valeurs de la variable sur la durée d'un état quelconque d'un acteur. Si elles entrent dans des spécifications de mise en tableau, on ne calcule la durée en Modgen que pour la période où l'acteur reste dans le domaine d'un tableau. Ainsi, si un filtre de tableau comprend le statut de résidence, on prendra uniquement en compte dans la durée d'un acteur immigré le temps où celui-ci a été résident canadien. Quelques-unes de ces fonctions produisent des données sur les états pour diverses «périodes» (c.-à-d. périodes durant lesquelles l état prend une valeur particulière). Ces fonctions de période se classent en deux catégories, à savoir celles qui produisent des valeurs pour une période «courante» et celles qui produisent des valeurs pour une période «antérieure». Ces deux catégories de fonctions se comportent différemment. En particulier, les fonctions de période «courante» ont une forme en dents de scie; leur valeur revenant à zéro à la fin de chaque période; tandis que les fonctions de période «antérieure» ont une forme en escalier. active_spell_delta (variable, état, variable d'analyse ) Il s'agit du changement que la variable d'analyse a subi depuis que la variable principale est dans un état quelconque. Ainsi, la valeur active_spell_delta (dfle, MILD_DIS, earnings) somme le revenu gagné pendant la période actuelle d'invalidité légère dans la simulation. active_spell_duration (variable, état ) Il s'agit de la durée d'un état depuis la dernière transition ou passage hors d'un autre état dans la simulation. Si l'intéressé a été dans le même état toute sa vie jusqu'ici, la valeur est nulle. Ainsi, la active_spell_duration (dfle, MILD_DIS) indique la durée de la période actuelle d'invalidité légère dans la simulation. Prenons le cas de quelqu'un qui a vécu jusqu'à l'âge de 75 ans et qui, étant entré dans un état d'invalidité légère à 20 ans et en étant sorti à 25 ans, est revenu légèrement handicapé à 60 ans et l'est demeuré jusqu'à sa mort. La valeur de la fonction est de 0 avant l'âge de 20 ans, de 1 à 21 ans, de 2 à 22 ans et ainsi de suite jusqu'à 25 ans. À ce moment-là, elle retombe à 0 jusqu'à l'âge de 60 ans où elle se remet à augmenter d'une unité par an jusqu'au décès. active_spell_weighted_duration (variable, état, variable de pondération ) C'est la valeur pondérée de la active_spell_duration. Elle peut servir, par exemple, à établir le revenu gagné jusqu'ici dans la période actuelle (en cours) d'emploi. On fait intervenir la variable earnings rate comme la variable de pondération. completed_spell_delta (variable, état, variable d'analyse ) 32 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

41 Il s'agit du changement subi par la variable d'analyse pendant la dernière période où l'acteur s'est trouvé dans l'état en question. Ainsi, la valeur completed_spell_delta (dfle, MILD_DIS, earnings) somme le revenu gagné pendant la dernière période d'invalidité légère dans la simulation. completed_spell_duration(variable, état) Il s'agit du laps de temps où la variable a été dans l'état en question la dernière fois. Si l'acteur a toujours été dans cet état jusqu'ici dans sa vie, la fonction présente une valeur nulle. Ainsi, la completed_spell_duration (dfle, MILD_DIS) indique combien de temps l'intéressé a passé la dernière fois dans un état d'invalidité légère. Prenons le cas de quelqu'un qui a vécu jusqu'à 75 ans et qui, étant entré dans un état d'invalidité légère à 20 ans et en étant sorti à 25 ans, est redevenu légèrement handicapé à 60 ans et l'est demeuré jusqu'à sa mort. La valeur sera de 0 avant l'âge de 25 ans et de 5 jusqu'au décès de l'acteur. completed_spell_weighted_duration (variable, état, variable de pondération) C'est la variable pondérée de la completed_spell_duration. Elle peut servir, par exemple, à établir le revenu gagné pendant une période antérieure. On se sert alors de la variable earnings rate comme variable de pondération. duration(variable, état ) ou duration() Il s'agit du laps de temps où l'acteur a été dans tel ou tel état jusqu'ici dans la simulation. Si la variable et l'état ne sont pas spécifiés, la durée est la somme des années d'existence de l'acteur. C'est la même fonction que duration (life_status, ALIVE). Ainsi, la duration (dfle, MILD_DIS) indique tout le temps où quelqu'un a été dans un état d'invalidité légère dans sa vie. Prenons le cas de quelqu'un qui a vécu jusqu'à l'âge de 75 ans et qui, étant entré dans l'état d'invalidité légère à 20 ans et en étant sorti à 25 ans, redevient légèrement handicapé à 60 ans et le reste jusqu'à la fin de sa vie. La durée est de 0 avant 20 ans, de 1 à 21 ans, de 2 à 22 ans et ainsi de suite jusqu'à l'âge de 25 ans. La valeur de 5 est atteinte et reste telle quelle jusqu'à l'âge de 60 ans où elle se remet à augmenter d'une unité par an jusqu'au décès. duration_trigger(état, valeur, temps écoulé) Cette fonction est un état logique indiquant si la durée d'un état a atteint une certaine valeur. Ainsi, la valeur logique worked6months = duration_ trigger(employed, TRUE, 0.5 ) peut être VRAI si l'intéressé a travaillé au moins 6 mois et FAUX dans les autres cas. La fonction crée aussi implicitement un événement pour lequel la période d attente est égale à la durée précisée. Dans l exemple qui précède, la période d attente serait de 0,5 duration_counter(état, valeur, grandeur de l intervalle de temps); ou duration_counter(état, valeur, grandeur de l intervalle de temps, valeur maximale); Cette fonction est semblable à duration_trigger() mais elle détermine le nombre d intervalles d une grandeur précisée qui se sont écoulés depuis qu un état particulier a atteint une valeur particulière. Guide du concepteur de Modgen v Éléments du langage Modgen 33

42 p. ex., int curtate_age = duration_counter(alive, TRUE, 1) comptera le nombre d années écoulées depuis la naissance de la personne, c est-à-dire l âge de la personne en nombre entier. Les événements implicites seront également créés lors de chaque anniversaire. Étant donné la création d événements implicites, l utilisation de la fonction duration_counter() peut être coûteuse, puisqu elle peut continuer d être mise à jour (peut-être mensuellement) longtemps après qu elle soit devenue inutile (p.ex., après la retraite ou au-delà de la valeur la plus grande nécessaire pour une fonction temporelle). Par conséquent, il est possible d utiliser un quatrième argument facultatif : le dénombrement maximal pouvant être atteint. Une fois ce maximum atteint, Modgen cessera de mettre la valeur à jour. p. ex., int curtate_age_below_50 = duration_counter(alive, TRUE, 1, 50) dénombrera les années écoulées depuis la naissance de la personne à condition que ce nombre soit inférieur ou égal à 50. À tout moment de la vie d une personne, curtate_age_below_50 sera égal à l âge (en nombre entier) de la personne ou à 50. weighted_cumulation(état 1, état 2) L'état 1 est l'état dont on observe la somme. Chaque fois que la valeur de l'état 1 change, la différence est multipliée par la valeur de l'état 2 et additionnée à l'état dérivé. On peut utiliser ce nouvel état pour créer une version en dollars constants d'un état quelconque sommé en dollars courants. weighted_duration (variable, état, variable de pondération ) ou weighted_duration (variable de pondération) Cette fonction fait intervenir les valeurs de la variable de pondération, qui est toujours une variable de taux (taux de revenu, de salaire, etc.), dans une sommation sur la durée d'un état quelconque. Il s'agit essentiellement de transformer une variable de taux en une variable de sommation. Si la variable et l'état ne sont pas spécifiés au départ, la valeur de la fonction est la sommation de la variable de pondération jusqu'au stade actuel de la vie de l'acteur. Ainsi, la weighted_duration (dfle, MILD_DIS, earnings_rate) donne le revenu total de l'acteur pendant tout le temps où il s'est trouvé dans un état d'invalidité légère. Prenons le cas de quelqu'un qui a vécu jusqu'à l'âge de 75 ans, a été légèrement handicapé de 60 à 65 ans et a touché un revenu annuel de $. La valeur de weighted_duration est de 10000*1 à 60 ans, de 10000*2 à 61 ans et ainsi de suite jusqu'à 65 ans où elle s'établit à 10000*5 = Elle reste telle quelle le reste de la vie de l'acteur. Autres fonctions spéciales split(état, nom_partition) 34 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

43 Cette fonction répartit l'état selon les groupes de classification définis dans nom_partition. Se reporter aux exemples de la section «tableaux» de ce document. sqrt(état ) Cette fonction donne la racine carrée de la valeur de l'état. Elle peut seulement être employée dans les spécifications de tableaux. Définition des types de variable de modèle On doit également définir les types de variable de modèle qui, à leur tour, déterminent les états et les paramètres de modèle en Modgen. Chacun de ces types est décrit plus loin. Définition du type TIME Modgen a recours à la définition spéciale TIME pour distinguer les modèles discrets des modèles continus. Ce mot clé TIME est utilisé pour déclarer des états qui stockent une valeur de temps, et aussi pour définir la valeur de retour de quelques fonctions. Le système tire sa valeur de la définition du type time_type. real, counter, integer Ces trois types pourraient être utilisés pour déclarer des états d acteurs contenant des valeurs à virgule flottante (real), des valeurs intègres non négatives (counter) ou des valeurs intègres (integer). Les types C++ vraiment utilisés par le modèle sont contrôlés par les commands real_type, counter_type, et integer_type, respectivement. Ces types et les declarations pour les contrôler sont décrits davantage dans la section «Définition des états d'un modèle». Notons cependant que ces types ne sont pas permis dans la déclaration de paramètres; ils ne peuvent être utilisés que pour déclarer des états. Ranges Une range est définie comme un intervalle de nombres entiers servant à la détermination de la taille des paramètres de modèle ou des états en forme matricielle (tableau). Syntaxe range name { min, max }; // étiquette Exemples // la fourchette, LIFE, est définie par les nombres entiers 0 à 100 range LIFE { 0, 99 }; // durée de vie // la fourchette, DFLE_AGE, est définie par les nombres entiers 15 à 100 Guide du concepteur de Modgen v Éléments du langage Modgen 35

44 range DFLE_AGE { 15, 99 }; // âge au moment des changements dfle Partitions La partition est un ensemble de points limites d'un état continu. Elle est employée habituellement dans la spécification des dimensions des paramètres du modèle (comme on l'indique ci-après) ou dans les tableaux et dans les expressions d'identité comme argument de la fonction split. On ne peut pas recourir à des partitions pour déclarer des états. Syntaxe partition name { number,..., number }; où number est un type double. Exemples partition AGE_GROUP1 { 15, 20, 25, 30, 35, 40, 45, 50 }; parameters { float AvgIndWage[AGE_GROUP1]; // salaire moyen dans l'industrie }; Types de classification Par type de classification, on entend un ensemble de niveaux avec leurs étiquettes. Il peut servir à définir la dimensionnalité d'un état ou d'un paramètre de modèle. Syntaxe classification name { // <codelang> étiquette <//codelang2 étiquette2 > level, //<codelang1> étiquette1 <//codelang2 étiquette2 > level, //<codelang1> étiquette1 <//codelang2 étiquette2 > level //<codelang1> étiquette1 <codelang2 étiquette2 > }; Exemples // la classification, SEX, est définie par ces deux types de classification de SEX { // Sexe FEMALE, // Femme MALE // Homme 36 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

45 }; // la classification, DFLE_STATE, est définie par quatre catégories // d'état d'invalidité classification DFLE_STATE { // État DFLE NO_DIS, // Aucun handicap MILD_DIS, // Handicap léger MODERATE_DIS, // Handicap moyen SEVERE_DIS // Handicap grave }; Agrégations des classifications dans les modèles fondés sur les cas et dans les modèles temporels Une fonction spéciale convertit les valeurs d une classification aux valeurs d une deuxième classification, à condition que la deuxième soit une agrégation stricte de la première. Pour exécuter la transformation, une correspondance doit être obtenue entre les états définis selon la première et selon la seconde classification dans le code source mpp au moyen de l énoncé «agrégation», avec la syntaxe suivante : aggregation aggregated_classification, detailed_classification { }; aggregated_item, detailed_item, aggregated_item, detailed_item, aggregated_item, detailed_item «aggregation» est un mot-clé Modgen, tandis que «aggregated_classification», «detailed_classification», «aggregated_item» et «detailed_item» se rapportent aux classifications agrégatives et détaillées définies précédemment ainsi qu'à leurs éléments. Précisons qu'il n'y a pas de virgule avant l'accolade de fermeture («}»). Si une agrégation a été définie par passage de la classification XXX à la classification YYY et que l état XXX est défini selon la classification XXX, alors aggregate(statexxx, YYY) produira la valeur correspondante d après la classification YYY. Les états dérivés en se servant de la fonction Guide du concepteur de Modgen v Éléments du langage Modgen 37

46 aggregate() peuvent être utilisés directement comme dimensions de tableaux, ainsi que dans les expressions et dans les fonctions de l utilisateur. Modgen crée aussi des fonctions qui peuvent être utilisées pour établir les correspondances entre diverses classification. Pour chaque paire de classifications XXX et YYY pour laquelle une agrégation a été définie, Modgen créera une fonction XXX_To_YYY(eLevel) qui accepte comme argument un niveau de classification XXX et produit un niveau de classification YYY. Ces fonctions peuvent être utilisées dans PreSimulation() et UserTables(), ainsi que dans des expressions ou des fonctions d acteur, mais ne peuvent pas être utilisées comme dimensions de tableaux. L exemple qui suit illustre le processus. Les résultats d échantillon sont indiqués après le code. classification PROVINCE { //EN Province NFLD, //EN Newfoundland PEI, //EN P. E. I. NS, NB, QUE, ONT, MAN, //EN Nova Scotia //EN New Brunswick //EN Quebec //EN Ontario //EN Manitoba SASK, //EN Saskatchewan ALTA, //EN Alberta BC, YUK, //EN British Columbia //EN Yukon NWT //EN N. W. T. }; classification REGION { //EN Region R_ATLANTIC, //EN Atlantic 38 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

47 R_QUEBEC, R_ONTARIO, //EN Quebec //EN Ontario R_PRAIRIES, //EN Prairies R_ALBERTA, R_BC //EN Alberta, //EN British Columbia }; aggregation REGION, PROVINCE { //EN De province à région R_ATLANTIC, NFLD, R_ATLANTIC, PEI, R_ATLANTIC, NS, R_ATLANTIC, NB, R_QUEBEC, QUE, R_ONTARIO, ONT, R_PRAIRIES, MAN, R_PRAIRIES, SASK, R_ALBERTA, ALTA, R_BC, R_BC, BC, YUK, R_ALBERTA, NWT }; actor Person { PROVINCE province; //EN Province REGION region = aggregate( province, REGION ); //EN Region REGION region2 = PROVINCE_To_REGION( province ); //EN Region }; Guide du concepteur de Modgen v Éléments du langage Modgen 39

48 table Person TB_PROV [ dominant ] { province+ * { unit, duration() } }; table Person TB_REGION [ dominant ] { aggregate(province,region)+ //EN Region * { unit, duration() } }; Les deux tableaux produits par un modèle d essai sont présentés plus bas. Notez que la valeur de «unit» obtenue si l on utilise la classification REGION n est pas égale à la somme des valeurs correspondantes obtenues en utilisant la classification PROVINCE. Cette situation tient au fait que les transitions à l intérieur des régions ne sont pas mesurées dans le tableau qui a REGION comme dimension de classification. Tableau : TB_PROV Province Unit Duration() Terre-Neuve Î.-P.-É Nouvelle-Écosse Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

49 Nouveau-Brunswick Québec Ontario Manitoba Saskatchewan Alberta Colombie-Britannique Yukon T.N.-O Total Tableau : TB_REGION Région unit duration() Atlantique Québec Ontario Prairies Alberta, Colombie-Britannique Total Définition des paramètres de modèle Il doit exister au moins un fichier de paramètres de modèle spécifiés par l'utilisateur pour que la simulation du modèle ait lieu. Les paramètres doivent être définis tant dans le code de modèle Modgen (dans un fichier.mpp) que dans le fichier Guide du concepteur de Modgen v Éléments du langage Modgen 41

50 paramétrique (fichier.dat) si on veut que le fichier exécutable du modèle s'en serve avec succès. Lorsqu il manque un paramètre dans les fichiers de paramètres, Modgen indique une erreur. Si un paramètre existe dans les fichiers de paramètre mais est inconnu du modèle, Modgen affichera un message d erreur mais continuera. L utilisateur pourra encore voir les paramètres. Si une simulation était en exécution, le message sera également affiché dans le fichier de journalisation. Dans une telle situation, la simulation continuera. Modgen est capable de créer un paramètre de modèle à partir de deux paramètres spécifiés par l'utilisateur. Ce programme peut accélérer l'exécution si le paramètre endogène est sans cesse repris dans la simulation. La taille de tous les paramètres de modèle est définie par des catégories (classification, range ou partitions) Syntaxe de définition de paramètres de modèle dans les fichiers.mpp parameters <group_name> { type name[size]...[size]; }; ou : Syntaxe de définition de paramètres de modèle dans les fichiers.dat parameters <group_name> { type name[size]...[size] = <( repeater)>{ value, value,..., value } }; Modgen reconnaît les nombres exprimés en notation scientifique (avec mantisse et exposant) dans les fichiers.dat. Voici quelques exemples : 1E-10, 2.5e100, 0.3E+101 On peut entrer les descriptions des paramètres sur une ligne séparée avant la définition du paramètre, ou encore les faire suivre sur la même ligne que la définition. La syntaxe se présente comme suit (les < > sont facultatifs) : //<codelang1> étiquette1 <décimales=n> <//codelang2 étiquette2 > Dans les fichiers d entrée des paramètres, les commentaires d une seule ligne peuvent compter jusqu à caractères. Pour plus de renseignements sur les décimales des paramètres, se reporter aux «Décimales de paramètre». numeric 42 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

51 Les paramètres de modèle numériques sont int, long, float ou double. Exemple de définition dans le fichier.mpp // échelle des gains annuels selon l'état d'invalidité float annual_earnings_scale[dfle_state]; Exemple de définition dans le fichier.dat // échelle des gains annuels selon l'état d'invalidité float annual_earnings_scale[dfle_state] = { , , , 0.0 } logical Modgen accepte la définition de paramètres logiques. Les valeurs des paramètres logiques dans les fichiers.dat peuvent être uniquement TRUE ou FALSE. Exemple logical Alive = {TRUE}; cumrate En modélisation de simulation, il est possible qu'un acteur passe d'un état quelconque à un autre parmi plusieurs. Ainsi, un bon état de santé peut se détériorer et devenir médiocre ou passable. On a l'habitude d'exprimer des probabilités de transition. S'il faut se reporter à un nombre aléatoire pour juger si une transition a eu lieu ou non, les paramètres appartiennent au type cumrate. Dans ce cas, la sommation des probabilités donne l'unité sur les [i] dimensions du paramètre. Ainsi, les dimensions antérieures du tableau conditionnent ces probabilités. Précisons enfin que les paramètres de modèle ne sont pas entrés comme valeurs cumulées de probabilité, Modgen cumulant les valeurs quand il y a accès par la fonction Lookup_. Exemples // cet exemple n'apparaît pas dans simpex // le paramètre de modèle, CumImmig, est une matrice à trois dimensions // dont la taille est déterminée par la classification SEX, la fourchette YEAR // et la fourchette IMM_AGE. // les valeurs de CummImmig expriment les probabilités de l'âge d'une personne // au moment de son immigration, conditionnées selon son âge et l'année Guide du concepteur de Modgen v Éléments du langage Modgen 43

52 // de la simulation. cumrate CumImmig[SEX][YEAR][IMM_AGE]; // cet exemple ne paraît pas dans simpex // le paramètre de modèle, CumBirth, est une matrice à trois dimensions // dont la taille est déterminée par la classification SEX, la fourchette // YEAR_OF_BIRTH, et la classification PROVINCE. // les valeurs de CumBirth expriment la probabilité que la personne se fasse // soigner dans une année et dans une province données, conditionnée selon // le sexe de cette personne cumrate [2] CumBirth[SEX][YEAR][PROVINCE]; piece_linear Le paramètre de modèle du type piece_linear met un ensemble de N points (valeurs X et Y) dans un espace bidimensionnel : x[1], y[1], x[2], y[2],..., x[n], y[n]. Les valeurs X doivent être par ordre croissant (c.-à-d. x[1] < x[2] <... < x[n] ). Cet ensemble définit ainsi une fonction de suite linéaire y( x ) : for x <= x[1] : y(x) = y[1] for x[k] < x <= x[k+1]: y(x) = y[k] + ( y[k+1] - y[k] ) / ( x[k+1] - x[k] ) * ( x - x[k] ) for x > x[n]: y(x) = y[n] Le paramètre de ce type doit être unidimensionnel et présenter un nombre pair de valeurs. Sa dimension doit être une fourchette (range). Exemple // L'exemple suivant ne paraît pas dans simpex piece_linear WagePoints[WAGE_POINT_VALUES] file Un paramètre de type «file» fournit le nom d'un fichier que l'utilisateur peut changer d'un scénario à un autre. Par exemple, l'utilisateur pourrait changer un fichier de départ de micro données utilisé dans une simulation avec un 44 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

53 paramètre de type «file». Un paramètre de type file est déclaré dans un fichier de code source d'un modèle (fichier.mpp) comme dans l'exemple suivant : parameters { file my_file; //EN File for testing }; La valeur d'un paramètre de type file est donnée dans un fichier d'entrée de paramètres (fichier.dat) comme séquence de caractères entre guillemets : parameters { file my_file = "C:\StatCan\tmp\thing.txt"; }; Un modèle Modgen fixe le répertoire courrant au répertoire du scénario. Donc, un nom de fichier précisé avec un chemin relatif est interprété relativement au répertoire du scénario. Par exemple, thing.txt (sans chemin en tête) veut dire le fichier «thing.txt» qui se trouve dans le répertoire du scénario, et «..\thing.txt» veut dire le fichier «thing.txt» qui se trouve dans le répertoire mère du scénario. Des matrices de paramètres de type file ne sont pas permises. Des paramètres de type file générés par le modèle («model_generated») ne sont pas permis. Guide du concepteur de Modgen v Éléments du langage Modgen 45

54 Paramètres créés par le modèle et fonction de PreSimulation Les paramètres créés par le modèle sont déclarés comme les paramètres ordinaires fournis par l'utilisateur, la seule différence des définitions étant le mot clé model_generated avant le type de paramètre. Pour les paramètres créés par le modèle, aucune entrée n'est nécessaire dans les fichiers de données (.dat). Modgen initialise tous les paramètres déclarés comme étant produits par le modèle à la valeur zéro au moment de leur création. Syntaxe de définition des paramètres créés par le modèle dans les fichiers.mpp model_generated type name [size]...[size]; Chaque modèle peut maintenant définir une fonction spéciale dite de présimulation qui ne prend aucun argument ni ne produit de résultats et qui, d'après les paramètres d'entrée, devrait servir à l'affectation des valeurs des paramètres créés par le modèle. La fonction soutient tous les types du langage C++ et est exécutée après que les paramètres d'entrée ont été lus, mais avant que ne débute la simulation. Son utilisation est facultative. Les paramètres de tous les types ont leur place dans la définition des paramètres créés par le modèle. Comme pour les paramètres d'entrée, les valeurs affectées en PreSimulation() devraient être les valeurs initiales. Modgen procédera à toutes les transformations (ex. cumrate.) après appel de la fonction PreSimulation(). Il y aura aussi validation des paramètres à ce moment-là. Exemples // L'exemple suivant n'est pas pris de l'exemple simple parameters {... int DiseasesModeled[DISEASES]; float MortHazards[DISEASES]; model_generated cumrate NonModCauseOfDeath[DISEASES];... }... void PreSimulation() { 46 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

55 int nindex; for ( nindex = 0; nindex < SIZE( DISEASES ); nindex++ ) { NonModCauseOfDeath[nIndex] = DiseasesModeled[nIndex]? 0 : MortHazards[nIndex]; } } Groupes de paramètres Les groupes de paramètres permettent au concepteur du modèle de regrouper les paramètres aux fins de sélection, en appliquant l'option interactive de l'onglet Affichage groupe. Les groupes de paramètres ne peuvent être définis que dans un fichier.mpp. Un paramètre peut appartenir à plus d'un groupe. Un groupe de paramètres peut comprendre des paramètres et/ou d'autres groupes de paramètres. Un groupe ne peut pas être membre de lui-même, directement ou indirectement. En tel cas, Modgen génère une erreur de «dépendance circulaire». Syntaxe parameter_group groupname{ parameter_name groupname,..., parameter_name groupname }; Exemple // Cet exemple n'est pas tiré de simpex parameter_group GDP_DEFLATOR { // paramètres de déflation du PIB BasketUpdateTime, DeflatorComputeTime, DeflatorCommodThresh, DeflatorStoreThresh, PaascheFactor }; Paramètres et groupes de paramètres créés par le modèle Le mot-clé model_generated_parameter_group fonctionne comme parameter_group, mais s applique uniquement aux paramètres créés par le modèle. Ces derniers ne peuvent plus faire partie d un groupe de paramètres. Vous devrez Guide du concepteur de Modgen v Éléments du langage Modgen 47

56 utiliser un groupe de paramètres créé par le modèle pour ces paramètres. Les seuls paramètres pouvant faire partie de ce nouveau groupe sont les paramètres créés par le modèle. Dépendances et prolongements des paramètres Les prolongements de paramètres permettent au concepteur du modèle d'initialiser un paramètre avec un nombre moins élevé de points de données que ne l'exige la définition (cependant, on remplit complètement un certain nombre de tranches de première dimension). On peut ensuite prolonger le paramètre dans la première dimension en recourant à l'une des deux définitions de prolongement que soutient Modgen. Syntaxe extend_parameter parameter_name ; extend_parameter parameter_name related_parameter_name ; On trouve les définitions des prolongements dans les fichiers.mpp. La première méthode prolonge les données en répétant la dernière tranche qui s'y trouve. La deuxième méthode utilise un paramètre unidimensionnel associé, et nécessite que le paramètre étendu et le paramètre apparenté soient toutes les deux de type range (fourchette) et que la fourchette correspondant au paramètre étendu soit contenue entièrement à l intérieur de la fourchette correspondant au paramètre apparenté. On prolonge ensuite le paramètre initial en utilisant comme facteurs de multiplication des valeurs ainsi stockées les ratios calculés entre les cellules correspondantes du paramètre associé. Cette méthode est fort utile à l'égard des paramètres de séries chronologiques qui comportent des années historiques et prévues (le temps doit être la première dimension). Un paramètre associé ne peut servir qu'à prolonger des paramètres du type double. Exemples : extend_parameter UniTuitionFees ; extend_parameter MaxLoan AvgIndWage ; Le suivant est un exemple dans lequel la fourchette correspondant au paramètre étendu est contenue entièrement à l intérieur de la fourchette correspondant au paramètre apparenté. range MODELED_YEAR { 1985, 2099 }; range CCTUT_MODELED_YEAR { 1980, 2101 }; 48 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

57 double CCTuitionFees[MODELED_YEAR][PROV_OF_STUDY][CC_TUITION_FOS]; double CCTuitionFeeIndex[CCTUT_MODELED_YEAR]; extend_parameter CCTuitionFees CCTuitionFeeIndex ; Les prolongements de paramètres sont utiles lorsque les paramètres renferment une valeur en dollars. Ainsi, il est possible de faire une prévision des valeurs au-delà des années historiques stockées dans le fichier en utilisant un indice reposant sur le salaire moyen dans l'industrie, comme ci-avant. L'éditeur visuel indique quelles sont ces valeurs en les affichant en gris pâle dans la grille. Décimales de paramètre L'utilisateur du modèle pourra vouloir indiquer le nombre de décimales enregistrées dans un paramètre numérique. Contrairement aux décimales de l'expression du tableau, les décimales de paramètre servent à la fois au formatage de la valeur affichée et à l'arrondissement d'une valeur enregistrée (pour ce qui est des expressions de tableau, les décimales servent uniquement à formater la valeur affichée). Les décimales de paramètres s'avèrent particulièrement utiles pour les paramètres prolongés (surtout ceux qui renferment une valeur en dollars). Pour indiquer le nombre de décimales de paramètre, il faut inclure la chaîne decimal= dans l'étiquette du paramètre (la même chose que dans les expressions de tableau). Exemple //EN Income exemption decimals=0 //FR Exemption du revenu double IncomeExemption[MODELED_YEAR] = { (7) 600, }; Les décimales sont précisées dans les fichiers.mpp. La valeur implicite des décimales de paramètre est 1, ce qui signifie aucune limite quant au nombre de décimales et aucun formatage de l'affichage. En général, toutes les valeurs négatives se présentent ainsi. Paramètres invisibles La fonction «hide» est utilisée pour empêcher des paramètres d être visibles dans l interface de modèles. La syntaxe de Guide du concepteur de Modgen v Éléments du langage Modgen 49

58 cette fonction est : hide(nom_ paramètre1, {nom_paramètre2, nom_paramètre3, }); Les arguments à la fonction «hide» sont des noms de paramètres ou des noms de groupes de paramètres qui doivent être cachés, séparés par une virgule. (Notons que cette même fonction «hide» peut aussi être utilisée pour cacher des tableaux dans l interface. Toutefois, les paramètres et les tableaux ne peuvent pas être combinés dans un même appel à cette fonction.) L utilisation du nom d un groupe de paramètres équivaut à l utilisation du nom de chaque member du groupe. Un groupe de paramètres sera affiché dans le modèle seulement s il contient au moins un paramètre qui n est pas caché. Les paramètres cachés ne seront pas inclus dans la base de données exportée en format Excel lorsque cette dernière est demandée, même si l utilisateur a demandé à inclure les paramètres du modèle. Sous-programmes de validation de paramètres et normalisation des paramètres Modgen prend en charge la validation des paramètres. Le concepteur du modèle n'a qu'à créer un sous-programme de validation de paramètres appelé «ValidateParameters». Puis, Modgen lance cette fonction lorsque la situation le justifie. Plusieurs définitions du sous-programme «ValidateParameters» peuvent figurer dans les fichiers.mpp. Ainsi, différents fichiers.mpp peuvent comporter des sous-programmes de validation destinés aux paramètres qu'ils contiennent. Le prototype du sous-programme «ValidateParameters» est le suivant : BOOL ValidateParameters(SCENARIO_EVENT eevent); «eevent» pouvant être l'une des constantes suivantes : SCENARIO_SAVE_EVENT, // le sous-programme est appelé à l'enregistrement du scénario. CELL_MOVE_EVENT, // le sous-programme est appelé lorsqu'une cellule de paramètre change. BLOCK_CHANGE_EVENT. paramètre sont modifiées. // le sous-programme est appelé lorsqu'une ou plusieurs cellules de SCENARIO_RUN_EVENT simulation en mode interactif (l'événement n'est pas traité en mode par lots). // le sous-programme est appelé tout juste avant le lancement de la Scénario/Valider. SCENARIO_MENU_EVENT // le sous-programme est appelé à l'aide de l'option de menu Le résultat de la fonction est TRUE ou FALSE. Si elle indique TRUE, la validation a réussi (certains ajustements peuvent avoir été effectués ou l'utilisateur peut avoir donné son approbation en cas de problème) et Modgen poursuit l'exécution de l'événement qui a appelé la fonction (Exécuter scénario, Enregistrer scénario, Changer données ou Déplacer cellule). Si FALSE est précisé, Modgen annule l'événement (par exemple, le Scénario n'est pas enregistré et 50 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

59 l'utilisateur revient à la fonction de modification du paramètre). En outre, Modgen offre des fonctions utilitaires qui peuvent être appelées par le sous-programme «ValidateParameters». Certains sous-programmes (GetParameterValue, SetParameterValue, CheckParameterTotals et NormalizeParameter) ne traitent que les paramètres de type numérique simple (entier, entier long, virgule flottante, double). BOOL ParameterChanged(const char *szname ); indique TRUE si le paramètre «szname» a été modifié dans la session d'édition actuelle. double GetParameterValue(const char *szname, ); produit la valeur de la cellule de paramètre précisée (indiquée par les arguments optionnels) void SetParameterValue(const char *szname, double dvalue, ); définit la valeur de la cellule de paramètre précisée (indiquée par les arguments optionnels) BOOL CheckParameterTotals(const char *szname, int ndimension, double ddesiredtotal, double dtolerancefactor); vérifie les totaux de la dimension précisée par l'argument «ndimension». Indique TRUE si tous les totaux de la dimension concordent avec «ddesiredtotal». Dans le cas de paramètres de type «int» ou «long», la concordance doit être parfaite; pour les paramètres de type «float» ou «double» la tolérance, quant à la comparaison, est déterminée par l'argument «dtolerancefactor». Ce facteur est multiplié par la précision de stockage du paramètre qui est indiquée par l'élément «decimals=» qui figure dans la définition du paramètre ou encore par la précision de stockage implicite (6 décimales pour le type «float» et 15 décimales pour le type «double»). La tolérance de comparaison est égale à dtolerancefactor * pow(10, - decimals ). Si le total d'une dimension précisée est de zéro, la valeur CheckParametersTotals n'indiquera pas que les données sont non valides. int ConfirmUndoParameterChanges(const char *szname); affiche une boîte de message qui permet à l'utilisateur d'annuler tous les changements apportés aux paramètres en cas d'échec du sous-programme de validation. Le code produit indique le bouton de la boîte de message qui a été sélectionné (IDYES, IDNO ou IDCANCEL). Le modélisateur peut ensuite prendre les mesures qui s'imposent en fonction du code précisé. BOOL NormalizeParameter(const char *szname, int ndimension, double ddesiredtotal); remet à l'échelle le paramètre d'après le ratio du total souhaité et le total réel de la dimension indiquée. Après cette opération, les totaux de paramètre de la «ndimension» doivent être suffisamment près du total voulu. Indique TRUE si le paramètre a été modifié durant le processus de normalisation. Si le total d'une dimension précisée est de zéro, le sousprogramme NormalizeParameter ne tente pas de le normaliser. int ConfirmCallToCorrectionRoutine(const char *szname ); ou int ConfirmCallToCorrectionRoutine(); Cette fonction offre deux prototypes. La fonction peut être appelée en cas d'échec de la validation d'un paramètre Guide du concepteur de Modgen v Éléments du langage Modgen 51

60 particulier (prototype avec argument) ou d'un groupe de paramètres. Elle affiche une boîte de message qui indique à l'utilisateur que la validation de paramètre a échoué et qui lui demande s'il souhaite lancer le sous-programme de correction. Le code produit indique le bouton de la boîte de message qui a été sélectionné (IDYES, IDNO ou IDCANCEL). Le modélisateur peut ensuite prendre les mesures qui s'imposent en fonction du code précisé. void MessageValidationFailed ( const char *szname ); ou void MessageValidationFailed() ; affiche simplement un message d erreur indiquant que la routine de validation du paramètre s est soldée par un rejet. Elle est similaire à la fonction «ConfirmCallToCorrectionRoutine», mais la boîte de message ne contient que le bouton OK et ne pose aucune question concernant l appel de la routine de correction. La fonction accepte un argument facultatif qui est le nom d un paramètre si le message a trait à un paramètre particulier. Un exemple de sous-programme de validation de paramètres figure ci-dessous : BOOL ValidateParameters( SCENARIO_EVENT eevent ) { BOOL bproceed = TRUE; int nresult; switch ( eevent ) { case SCENARIO_SAVE_EVENT: if ( ParameterChanged( "Coefficients" ) ) { if (!CheckParameterTotals( "Coefficients", 1, 1.0, 100 ) ) { nresult = ConfirmCallToCorrectionRoutine("Coefficients"); if (nresult == IDYES) { NormalizeParameter( "Coefficients", 1, 1.0 ); } else if (nresult == IDCANCEL){ bproceed = FALSE; 52 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

61 } } } break; case CELL_MOVE_EVENT: break; case BLOCK_CHANGE_EVENT: break; case SCENARIO_RUN_EVENT: if (!CheckParameterTotals( "Coefficients", 1, 1.0, 100 ) ) { nresult = ConfirmCallToCorrectionRoutine("Coefficients"); if (nresult == IDYES) { NormalizeParameter( "Coefficients", 1, 1.0 ); } else if (nresult == IDCANCEL){ bproceed = FALSE; } } break; case SCENARIO_MENU_EVENT: if (!CheckParameterTotals( "Coefficients", 1, 1.0, 100 ) ) { nresult = ConfirmCallToCorrectionRoutine( "Coefficients" ); if ( nresult == IDYES ) { NormalizeParameter( "Coefficients", 1, 1.0 ); } } break; Guide du concepteur de Modgen v Éléments du langage Modgen 53

62 default:; } return bproceed; } Étiquettes de symbole Différents symboles définis dans les fichiers mpp peuvent être étiquetés à l'aide de l'instruction LABEL. Cette instruction est utile pour les modèles multilingues, qui peuvent ainsi étiqueter les symboles dans une seule langue (par défaut) dans l'ensemble principal de fichiers mpp et offrir des étiquettes pour des langues additionnelles dans des fichiers mpp distincts. On peut en outre ajouter les étiquettes immédiatement après la définition de symbole, comme dans le fichier Person.mpp ci-après. La syntaxe de l'étiquette de symbole est la suivante : ou // LABEL (symbole ) texte // LABEL (symbole, langue ) texte Chaque étiquette (c.-à-d. texte dans les déclarations ci-dessus) peut compter jusqu à 255 caractères. Exemples (tirés du modèle Simpex fourni avec l'installation de Modgen) : SimpexEN.mpp : classification SEX { //EN Gender FEMALE, //EN Female MALE //EN Male }; SimpexFR.mpp : // LABEL (SEX, FR ) Sexe // LABEL (FEMALE, FR ) Féminin // LABEL (MALE, FR ) Masculin Person.mpp : actor Person //EN Individual 54 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

63 { int earnings = {0} ; //EN Lifetime earnings to date DFLE_STATE dfle = {NO_DIS}; //EN Disability State LIFE_STATE life_status = {ALIVE}; //EN Life Status }; PersonFR.mpp : // LABEL (Person, FR ) Individu // LABEL (Person.earnings, FR ) Gains totaux à ce jour // LABEL (Person.dfle, FR ) Situation-handicapé // LABEL (Person.life_status, FR ) Situation vie StandTab.mpp : table Person X08_AvgEarnByAge //EN Cases and their average earnings by age group { split( age, AGE_GROUPS )+ //EN Age Group * { unit, //EN Persons earnings / duration() //EN Avg earnings } }; StandTabFR.mpp : // LABEL (X08_AvgEarnByAge, FR ) Cas et gains moyens par groupe d'âge // LABEL (X08_AvgEarnByAge.Dim0, FR ) Groupe d'âges // LABEL (X08_AvgEarnByAge.Expr0, FR ) Personnes // LABEL (X08_AvgEarnByAge.Expr1, FR ) Gains moyens Pour étiqueter les modules, les classifications, les plages (ranges), les partitions, les acteurs et les tableaux, utilisez leurs noms à titre de nom de symbole dans l'instruction LABEL. Pour étiqueter les membres d'acteur (par exemple les états), précisez leurs noms précédés du nom d'acteur et d'un point Guide du concepteur de Modgen v Éléments du langage Modgen 55

64 (par exemple Personne.gains). Pour étiqueter une dimension classificatoire d'un tableau, précisez un nom de dimension (Dim0, Dim1,) précédé du nom du tableau et d'un point (par exemple X08_AvgEarnByAge.Dim0). Pour étiqueter une expression de table, précisez le nom de l'expression (par exemple Expr0, Expr1, ) précédé du nom du tableau et d'un point (par exemple X08_AvgEarnByAge.Expr0). Notes relatives aux symboles Les notes relatives aux permettent au concepteur du modèle d'intégrer la documentation du modèle Modgen dans le modèle compilé afin que les utilisateurs du modèle puissent y recourir. Diverses notes inscrites dans les fichiers mpp et DAT (plus la note de scénario mémorisée dans le fichier SCE) sont maintenant préformatées en paragraphes et listes avant d être affichées dans l environnement interactif du modèle. Les règles qui suivent s appliquent lors du formatage d une note. Exemple : /* NOTE ( MortalityModule, FR ) Tous les caractères de tête ayant la forme d espace blanc (espaces et tabulations) sont supprimés de chaque ligne du texte de la note. Un ensemble de lignes non vides délimitées par des retours de chariot et nouvelles lignes (CRLF) seront considérées comme étant un paragraphe et formatées en tant que tel. Une ligne vide (\n\n) présente un nouveau paragraphe. Une ligne qui commence par un tiret («-») sera considérée comme étant un élément d une liste et sera formatée en tant que tel. Voici un paragraphe imaginaire qui a été mis en retrait aux fins d illustration. Il est considéré comme étant un paragraphe parce qu il se termine par une ligne en blanc, c est-à-dire \n\n. - Il s agit de l élément n o 1 d une liste ordonnée, qui comporte un retour automatique à la ligne parce qu il est long. - Il s agit de l élément n o 2 de la liste. 56 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

65 Ici nous avons un autre paragraphe. Si ce paragraphe avait commencé immédiatement après la liste, une ligne en blanc aurait quand même été insérée, puisqu un paragraphe doit être séparé du texte qui le précède ou qui le suit par une ligne en blanc. */ Affiché comme suit : Voici un paragraphe imaginaire qui a été mis en retrait aux fins d illustration. Il est considéré comme étant un paragraphe parce qu il se termine par une ligne en blanc, c est-à-dire \n\n. - Il s agit de l élément n o 1 d une liste ordonnée, qui comporte un retour automatique à la ligne parce qu il est long. - Il s agit de l élément n o 2 de la liste. Ici nous avons un autre paragraphe. Si ce paragraphe avait commencé immédiatement après la liste, une ligne en blanc aurait quand même été insérée, puisque les paragraphes doivent être séparés du texte qui les précède ou qui les suit par une ligne en blanc. Lors de la sauvegarde de notes modifiables (note de valeur de paramètre, note de fichier de paramètre, note de fichier de scénario) dans leur fichier source, les paragraphes sont subdivisés en lignes d environ 80 caractères et des lignes en blanc sont insérées entre eux si elles ne le sont pas déjà. En outre, le concepteur du modèle peut indiquer dans les fichiers mpp et (ou) DAT pour quelles lignes supplémentaires les retours de chariot devraient être protégés sans devoir insérer des lignes en blanc. Pour le faire, il faut entrer un symbole Plus grand que («>») en tant que premier caractère (outre les espaces et les tabulations) sur la ligne de texte. Le texte sera alors affiché au début de la nouvelle ligne et ne sera pas annexé au paragraphe précédent. Le caractère «>» proprement dit ne sera pas affiché. Les caractères d espace en blanc (espaces et tabulations) qui suivent le caractère «>» sont préservés lors de l affichage pour permettre le renfoncement du texte. Exemple (partie de la note de scénario du modèle SPPC Demand) : Guide du concepteur de Modgen v Éléments du langage Modgen 57

66 Les coefficients ont été générés à l aide de la méthodologie employée pour générer le scénario de printemps de Les coefficients, cependant, ont été révisés de façon à refléter la codification NOC de l EPA jusqu à la fin de Horizon d année : 1984 à 2008 Le scénario a été produit au départ par : > Projections des professions et études macro-économiques > Direction générale de la recherche appliquée, DRHC > On peut accoler une note à un symbole Modgen utilisé dans un modèle (module, classification, fourchette, partition, acteur, état, tableau, paramètre, groupe paramétrique, etc.). Il en existe deux catégories. Dans les fichiers.mpp, la note devrait décrire l'usage d'un symbole quelconque et dans un fichier.dat, la note devrait décrire les valeurs paramétriques particulières et être étiquetée comme une note de valeur dans les fenêtres des propriétés. La syntaxe d'une note de symbole (le code de langue est facultatif) s'écrit comme suit : /* NOTE (symbole <,codelang> ) text */ Le nom des symboles dans les dimensions de tableau et l'axe des expressions de tableau est un cas particulier : <tablename>.dim0, <tablename>.dim1. <tablename>.expr0, <tablename>.expr1 Ainsi, si l'axe des expressions représente la dernière dimension du tableau (c.-à-d. dans les colonnes), on pourra accoler des notes détaillées à chaque colonne du tableau. Exemple /* NOTE (WagePoints ) Le taux salarial est un taux de revenu relatif qui est mis à l'échelle (moyenne 1.0). De tels taux s'appliquent à l'ensemble des coûts et bénéfices des entreprises 58 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

67 (divisés par le nombre de personnes ) et permettent de calculer le revenu du consommateur. */ Dans la rédaction de notes relatives aux objets acteurs (états, éléments, etc.), le nom du symbole est le nom de l'acteur suivi d'un point et du nom de l'objet (p. ex., person.mar_status). Documentation Menu d aide Le menu d aide disponible de l interface du modèle peut avoir jusqu à cinq sous-items activés : Aide pour <Nom du Modèle> Aide pour Modgen (donne accès au Guide de l interface visuelle de Modgen) Notes de publication <Nom du Modèle> Notes de publication Modgen À propos de: La troisième choix, «Notes de publication <Nom du Modèle>», est activée si les notes figurent dans le répertoire du modèle. Les noms de fichiers pour les notes de publication du modèle doivent avoir la forme type suivante : <Nom du modèle>notes_<code de langue>.htm. (p. ex., SimpexNotes_FR.htm). Si aucune langue n est spécifiée dans le modèle, le nom devient <Nom du modèle>notes.htm. La cinquième choix, «À propos de», affichera les numéros de version du modèle et de Modgen et présentera des boutons pour permettre d afficher la licence du modèle ou celle de Modgen. Toutefois, le bouton de licence du modèle est activé uniquement si le fichier de licence figure dans le répertoire du modèle. Les noms de fichiers doivent avoir la forme type suivante : <Nom du modèle>licence_<code de langue>.htm (p. ex., SimpexLicence_FR.htm) Guide du concepteur de Modgen v Éléments du langage Modgen 59

68 Fonction de documentation automatisée sur le modèle Modgen a la capacité de produire et d utiliser de la documentation sur le modèle en format CHM. Voici une description de ce qui se passe lorsqu un utilisateur d un modèle Modgen demande à consulter l aide sur le modèle à partir du menu. Premièrement, Modgen détermine s il existe pour le modèle un fichier d aide CHM connexe à jour et si l environnement existant de l ordinateur accepte les fichiers d aide CHM. Si c est le cas, le fichier d aide CHM s affiche. Modgen recherchera et utilisera le fichier <Nom du modèle>1_<code de langue>.chm s il existe, permettant ainsi au concepteur du modèle de substituer de façon transparente un autre système d aide. En général, le projet d aide définissant <Nom du modèle>1_<code de langue>.chm devrait faire référence au fichier d aide de CHM produit par Modgen, c est-à-dire à <Nom du modèle>2_<code de langue>.chm. Il est conseillé aux concepteurs de modèles Modgen d appeler la commande de menu «Aide pour <Nom du modèle>» pour générer un fichier CHM à jour qui peut être livré avec un modèle. Ceci doit être fait pour chaque langue, si le modèle accepte plusieurs langues. Le fichier CHM ainsi produit est nommé <Nom du modèle>2_<code de langue>.chm, où <Nom du modèle> est le nom du modèle et <Code de langue> est la chaîne de caractères identifiant la langue pour les modèles qui acceptent plusieurs langues. Par exemple, la version française de la documentation produite pour le modèle LifePaths est nommée LifePaths2_FR.chm. Pour les modèles Modgen pour lesquels les langues ne sont pas précisées, les fichiers CHM sont appelés <Nom du modèle>1.chm et <Nom du modèle>2.chm. Mode aide Il est possible d exécuter un modèle en mode d aide, de façon comparable à l exécution en mode de documentation. Au lieu d exécuter la simulation, le modèle créera des fichiers d aide pour toutes les langues connues du modèle. La syntaxe à utiliser est la suivante (en prenant le modèle Simpex comme exemple) : D:\Simpex.exe help. Choix de la langue Les langues définies dans un modèle particulier sont en fait regroupées pour former un ensemble de langues. Dans chaque ensemble, les langues sont classées selon un ordre de préférence propre à chaque utilisateur. Exemple : 60 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

69 Simpex «connaît» deux langues : l anglais et le français. Si un utilisateur ouvre le modèle Simpex, puis sélectionne comme langue le français, la langue préférée pour l ensemble de langues {anglais, français} sera le français. Plus d un modèle peuvent utiliser le même ensemble de langues et auront, par conséquent, la même langue préférée pour un utilisateur particulier. Nous avons supposé que, si un utilisateur a le choix entre le français et l anglais et qu il choisit le français, il préférera systématiquement le français à l anglais. Donc, si un utilisateur change le choix de langue dans un modèle, il le modifiera pour tous les modèles comportant le même ensemble de langues. En outre, si un autre ensemble de langues contient au moins les langues de ce modèle, et si la langue préférée courante est la même que celle de l ensemble de langues du modèle, il y aura application du même principe de classement rationnel et modification éventuelle de la langue préférée. Exemple : Disons que nous avons un ensemble de langues 1 : LanguageSet = {English, French} pour lequel la langue préférée est l anglais et un autre ensemble de langues 2 LanguageSet = {English, French, Spanish} pour lequel la langue préférée est l anglais. Si un utilisateur ouvre un modèle utilisant l ensemble de langues 1 et choisi le français comme langue préférée, le système interprétera le changement d option comme signifiant que l anglais n est désormais plus la langue préférée et que celle-ci est maintenant le français. Modgen passera à travers la liste des ensembles de langues et, dans tous les cas où l anglais et le français figurent dans un ensemble, modifiera le choix de langue préférée de sorte qu elle devienne le français si la langue préférée était l anglais. Dans notre exemple, les deux ensembles de langues seraient modifiés de sorte que la langue préférée deviennent le français. Les renseignements sur les ensembles de langues et les langues préférées connues seront gardés dans le répertoire pour Guide du concepteur de Modgen v Éléments du langage Modgen 61

70 chaque utilisateur. Chaque fois qu il ouvrira un modèle contenant un ensemble de langues «inconnu» en mode interactif, l utilisateur verra apparaître la boîte de dialogue suivante lui demandant de choisir une langue avant que le modèle ne s ouvre. Puis, l ensemble de langues sera créé. Cette fenêtre de dialogue est aussi celle qui apparaît lorsque l utilisateur veut changer la langue (menu Affichage, Définir Langue). De nouveau, un utilisateur donné ne sera invité qu une seule fois en mode interactif à faire un choix au moyen de cette boîte de dialogue pour les modèles anglais/français. La réponse donnée pour un modèle anglais/français particulier sera mémorisée et appliquée à tous les modèles anglais/français. Lors de l installation de Modgen, il est demandé à l utilisateur de choisir une langue d installation. Les deux langues du programme d installation (anglais et français) sont utilisées pour créer un ensemble de langues et la langue choisie par l utilisateur devient la langue préférée de cet ensemble de langues pour l utilisateur en question. Autre Langues Le support pour le français ainsi que pour l anglais est intrinsèque à Modgen. Cependant, le support pour d autres langues peut être ajouté, avec l aide des fichiers «ModgenEN.mpp» et «ModgenFR.mpp» qui sont installés avec Modgen et qui se retrouvent dans le répertoire d installation de Modgen. Ces fichiers contiennent toutes les chaînes de caractères de l interface des modèles Modgen et pourraient servir comme point de départ pour un concepteur qui voudrait ajouter du support pour une tierce langue. Par exemple, un concepteur pourrait traduire le contenu de ModgenFR.mpp du français à l espagnol pour produire un fichier ModgenES.mpp et inclure ce fichier et une ligne languages définissant ES comme espagnol dans le projet d un modèle pour fournir une interface en espagnol. 62 Éléments du langage Modgen Guide du concepteur de Modgen v10.1.0

71 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Aperçu du programme de mise en tableau La façon classique de présenter les résultats du modèle est d'utiliser le programme de croisement de données. Celui-ci permet à l'utilisateur de spécifier une grande diversité de tableaux portant sur la population en simulation. Règle générale, les totalisations résument des données sur les éléments suivants (habituellement catégorisés par diverses variables de classification) : Valeurs des variables continues, par exemple, les salaires ou les coûts. Durée des états des acteurs. Nombre d'acteurs ou d'événements (changements d'état). À l'encontre des totalisateurs de croisement ordinaires, la mise en tableau par Modgen s'enrichit d'un élément supplémentaire, à savoir le temps. Pour maximiser l'efficacité des calculs et réduire au minimum l'utilisation des ressources, la sommation des totalisations en Modgen se fait «pendant l'exécution du programme». On peut se représenter les acteurs comme des personnes qui se déplacent dans le temps et séjournent dans les cases de tableaux à mesure que changent les états. Lorsqu'un acteur entre dans une case d'un tableau, les valeurs initiales des divers états dépendants sont mises de côté et le système augmente de 1 le nombre (qu'on appelle une unité) d'entrées dans la case. Lorsque l'acteur sort d'une case et que Modgen repère une demande d'avance du temps, il déclenche une mise à jour du tableau à l'aide des valeurs des états de sortie, des valeurs des états d'ouverture et des réglages de l'opérateur de sommation. L'opérateur de sommation indique à Modgen la façon de résumer les valeurs à l'intérieur de la case. L'opérateur le plus courant dans ce cas est la somme, cependant Modgen accepte aussi le minimum et le maximum. L'opération implicite (qu'on appelle delta) est un peu plus intéressante. Son rôle consiste à retrancher les valeurs d'entrée des valeurs de sortie et à ajouter le résultat au total cumulatif de la case. La méthode de sommation par delta fait Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 63

72 uniquement du sens à l'égard des états qu'on peut exprimer comme des valeurs cumulatives de la vie (il importe de se rappeler ce point au moment d'ajouter de nouveaux états à des acteurs). Les variables continues, comme les gains, répondent admirablement bien à ce critère en n'utilisant que très peu de ressources. Supposons qu'on a défini un acteur personne en lui accolant un état présentant les gains cumulatifs de sa vie et que nous désirons totaliser les gains moyens selon l'âge par intervalle d'un an. Chaque cas renferme un tel acteur et la simulation s'applique à 100 cas. Lorsque le premier acteur arrive, par exemple, à 30 ans, le système met de côté les gains qu'il a accumulés jusqu'à maintenant, il augmente l'unité de 1 pour cette case du tableau et laisse le temps s'écouler en faisant intervenir divers événements jusqu'à l'âge de 31 ans. À ce moment-là, ses gains cumulatifs à 30 ans seront soustraits de ses gains cumulatifs à 31 ans afin d'obtenir les gains de l'intervalle. Lorsque le deuxième cas se présente, les mêmes calculs ont lieu à l'entrée et à la sortie de la case, le résultat du numérateur s'ajoutant au total cumulatif des cas précédents. Et ainsi de suite pour les 100 cas. Dans le dernier cas, le système procède à une division pour connaître la moyenne. On remarquera que cette technique n'utilise aucune ressource informatique supplémentaire au processus de totalisation si le modèle comportemental sous-jacent met à jour la valeur des gains toutes les deux semaines. On pourrait utiliser l'unité comme dénominateur pour calculer la moyenne, mais ce serait mal choisir. Le processus de totalisation doit essentiellement reposer sur l'utilisation de durées. Supposons que vous désirez totaliser les gains annuels moyens par intervalle de dix ans plutôt que d'un an comme ci-avant. L'utilisation de l'unité comme dénominateur ne donnerait pas de bons résultats. Ce qu'on veut réellement, c'est diviser les gains par la durée de l'intervalle (dans ce cas-ci, 10, mais qui se trouve justement à se situer un au-dessus) et non par le nombre d'acteurs entrant dans la case. Pour obtenir la moyenne annuelle pour l'intervalle de dix ans, vous devez additionner les gains pendant l'intervalle de dix ans pour l'ensemble des acteurs et les diviser ensuite par la somme des intervalles pour tous les acteurs. Modgen fournit à cette fin des états dérivés, en l'occurrence l'état (duration)). Prière de se reporter à la section «États dérivés associés à la durée des états des acteurs» pour obtenir une liste complète de tels états. La méthode fonctionne bien dans le cas des gains, mais qu'arriverait-il si vous vouliez compter le nombre d'événements à l'intérieur d'un intervalle d'âge? On peut considérer les événements comme des changements de valeur d'un état. La totalisation est un delta d'intervalles des changements cumulatifs survenus à cet état pendant la vie de l'acteur. Ici encore, Modgen fournit des états dérivés qui peuvent calculer pour vous les sommations pendant la durée de vie. Par exemple, supposons que vous désirez totaliser le nombre de mariages à 30 ans pour 100 acteurs. Dans ce cas, la totalisation utilisera un état dérivé appelé entrances dont l'argument MARRIED spécifiera la variable marital_status. Combinée à l'opérateur cumulatif delta, la case présentera le nombre de mariages au cours de cet intervalle d'un an. Prière de se reporter à la section «États dérivés associés aux changements d état des acteurs» pour obtenir une liste complète de tels états. Les spécifications du tableau définies par la commande de mise en tableau sont contenues dans le fichier StandTab.mpp. Règle générale, les variables de classification, de partition ou logiques déterminent la dimensionnalité d'un tableau et les expressions de tableau, les valeurs des cases de ce tableau. Tous les tableaux sont liés à un acteur du modèle (d'habitude 64 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

73 une personne, l'acteur principal). Un filtre facultatif permet de produire des rapports sur des sous-ensembles de la population en simulation. L'étiquetage et la désignation de chaque tableau sont particulièrement utiles du point de vue de l écriture des résultats sur la feuille de calcul Excel et la base de données Access. Les concepteurs de modèles peuvent aussi définir des groupes de tableaux qu'ils utiliseront à l'option Affichage groupe de l'interface visuelle du modèle. De plus, si un utilisateur désire soustraire certains tableaux au moment de l'exécution, l'interface habituelle lui permettra de choisir le sous-ensemble de tableaux qui devront faire l'objet d'une sommation avant d'être envoyés à la sortie. On peut ainsi accélérer considérablement la simulation en retranchant les tableaux inutiles de passage donnés. Pour plus de renseignements sur les sorties de tableaux, prière de se reporter au Guide de l interface visuelle de Modgen. Définitions de tableau La syntaxe de la commande de mise en tableau s'écrit comme suit. Les < > crochets précisent les caractéristiques de la commande de mise en tableau qui sont facultatives. Syntaxe table <sparse> actor_name <table_name> <[filtering_criteria]> <// étiquette> { < dimension <+> <// étiquette de dimension> *> < dimension <+> *> { analysis dimension expression, <// étiquette d'expression > <options d'expression> <analysis dimension expression, <// étiquette d'expression > <options d'expression>> <analysis dimension expression <// étiquette d'expression > <options d'expression>> } <* dimension <+> < // étiquette de dimension > > } ; Si le tableau est très grand et très clairsemé (s'il contient de nombreux zéros), vous pouvez réduire la taille de la base de données de sortie en ajoutant le mot-clé «sparse» optionnel à l'instruction «table». Le nombre de dimensions d'un tableau est illimité. Utilisez les «*» pour délimiter le nombre de dimensions. L'étiquette Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 65

74 de dimension est facultative. Toutefois, si une étiquette n a pas été explicitement fournie, Modgen construira une étiquette dans cette langue en utilisant l étiquette dans cette langue de l état utilisée dans la dimension. Si elle n'est pas présente, on peut placer le caractère «*» sur la même ligne que la dimension. On peut aussi ajouter le caractère facultatif «+» pour indiquer au système qu'il doit calculer le nombre total de dimensions pour cette dimension de classification. Chaque tableau peut contenir uniquement une dimension d'analyse, mais un nombre illimité d'expressions séparées par des virgules avant l'étiquette d'expression. La dernière expression n'est pas suivie d'une virgule. Les options relatives aux expressions servent à préciser les décimales et les échelles pour les données dans le corps du tableau. Si la dimension d'analyse, par exemple, figure dans les colonnes de votre tableau (c.-à-d. qu'elle n'est suivie d'aucune déclaration de dimension), vous avez le choix de préciser des décimales et échelles différentes pour chaque colonne de votre tableau. Il n'est pas nécessaire d'indiquer un table_name puisque Modgen donnera par défaut les noms tableau X1, tableau X2, etc.). Toutefois, on recommande d'utiliser table_name pour les données qui doivent sortir en format Excel ou Access par le mode interactif. Une fois la simulation achevée pour tous les cas, on évalue les expressions de tableau avec les valeurs globales de ces états. Ainsi, les expressions qui représentent des ratios de variables présentent un rapport numérateur-dénominateur en valeur globale, et non pas la moyenne des ratios particuliers aux acteurs dans la simulation. Groupes de tableaux Les groupes de tableaux permettent au concepteur d'un modèle de regrouper des tableaux pour choisir ce qu'il désire à l'onglet Affichage groupe de l'option interactive. Ces groupes de tableaux peuvent uniquement être définis dans un fichier.mpp. Un tableau peut appartenir à un nombre illimité de groupes. Un groupe peut comprendre des tableaux et/ou d'autres groupes de tableaux. Un groupe ne peut pas être membre de luimême, directement ou indirectement. En tel cas, Modgen génère une erreur de «dépendance circulaire». La syntaxe de la définition d'un groupe de tableaux est semblable à celle d'un groupe de paramètres : table_group groupname { // étiquette table_name groupname,..., table_name groupname }; Exemple : table_group LOAN_TABLES { // Tables de prêts LOAN, FORGIVEN, INTRELIEF, LOANNEEDS }; 66 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

75 Expressions de tableau Les expressions de tableau, qui définissent le contenu des cases d'un tableau, peuvent comprendre le tabulation_operator, les états, les mots clés de sommation, les fonctions spéciales, le mot clé unit et les constantes numériques avec les opérateurs arithmétiques + - * / et la parenthèse (). Les expressions sont séparées par une «,» dans les spécifications de tableau. Mot clé unit La variable unit indique le nombre d'acteurs qui sont entrés dans chaque case d'un tableau. Elle sert donc à déterminer le nombre d'acteurs ayant un certain ensemble de caractéristiques à un certain stade de leur vie en simulation, ou encore un dénominateur permettant de calculer des moyennes pour les variables continues soumises à l'analyse. On doit utiliser ce mot clé avec circonspection. En effet, il arrive souvent, sans le vouloir, qu'on fasse un double compte, surtout dans les tableaux démographiques. Exemple 1 Dans ce tableau, on indique le nombre total d'acteurs personnes dans une simulation. Dans l'exemple, la variable spéciale unit est la seule expression de tableau qui soit spécifiée. Il n'y a pas de variable de classification dans les spécifications de tableau. On notera comment l'inclusion d'observations dans les spécifications de tableau se retrouvent dans les rapports produits. Spécification de tableau table Person X01_SimulatedCases // Nombre de cas simulés { { unit // Personnes } }; Résultat de tableau Tableau X01_SimulatedCases: Nombre de cas simulés Personnes Valeur Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 67

76 Personnes États On peut présenter les valeurs de variables continues à l'aide du programme de mise en tableau. Règle générale, les variables cumulées sur la vie d'un acteur se prêtent le mieux à une présentation sous forme de tableaux. Exemple 2 Dans cet exemple, le tableau présente les revenus de toute la population cumulés pendant sa vie (à l'échelle «millions de dollars»), ces mêmes revenus cumulés en moyenne individuelle, et le revenu annuel moyen de chaque personne. Spécification de tableau table Person X02_EarningsSummary // Sommaire des gains {...{ earnings, // Gains totaux de la population pour la vie (millions) scale=-6 earnings / unit, // Gains moyens pour la vie...} }; earnings / duration () // Gains annuels moyens pour la vie Résultat de tableau Tableau X02_EarningsSummary: Sommaire des gains Quantités sélectionnées Valeur Gains totaux de la population pour la vie (millions) 3296 Gains moyens pour la vie Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

77 Gains annuels moyens pour la vie Opérateurs de sommation Les mots clés de sommation contrôlent l'affectation d'états aux cases ou cellules d'un tableau pour l'ensemble des acteurs. On peut les interpréter comme des totaux cumulatifs ou des minimums/ maximums cumulatifs. Dans tous les cas, l'état peut être une expression d'état simple ou dérivée. delta(état) C'est l'opérateur sommatif par défaut. Ce mot clé affecte la différence entre la valeur d'un état à la première entrée d'un acteur dans une case d'un tableau et sa valeur à la sortie. delta2(état) Cet opérateur ressemble à l'opérateur delta () mais présente des valeurs quadratiques, fonction qui peut s'avérer utile dans le calcul d'erreurs types. max_delta(état) Cet opérateur ressemble à l'opérateur delta () mais présente la valeur maximale. max_value_in(état) Ce mot clé donne la valeur maximale de l état par rapport à l'ensemble du nombre d'entrées, à la première entrée de chaque acteur dans une case du tableau. max_value_out(état) Ce mot clé donne la valeur maximale de l état par rapport à l'ensemble du nombre d'entrées, à la sortie de chaque acteur dans une case du tableau. min_delta(état) Cet opérateur ressemble à l'opérateur delta () mais présente la valeur minimale. min_value_in(état) Ce mot clé donne la valeur minimale de l état par rapport à l'ensemble du nombre d'entrées, à la sortie de chaque acteur dans une case du tableau. min_value_out(état) Ce mot clé donne la valeur minimale de l état par rapport à l'ensemble du nombre d'entrées, à la Sortie de chaque acteur dans une case du tableau. nz_delta(état) Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 69

78 Ce mot clé donne 1 dans les cas où le mot clé delta () produirait une valeur non nulle et 0 dans les autres cas. nz_value_in (état) Ce mot clé donne 1 dans les cas où le mot clé value_in () produirait une valeur non nulle et 0 dans les autres cas. nz_value_out (état) Ce mot clé donne 1 dans les cas où le mot clé value_out () produirait une valeur non nulle et 0 dans les autres cas. value_in(état) Ce mot clé donne la valeur de l état à la première entrée de l'acteur dans une case du tableau. value_in2(état) Ce mot clé donne la valeur quadratique de l état à la première entrée de l'acteur dans une case du tableau. value_out(état) Ce mot clé donne la valeur de l état à la sortie de l'acteur d'une case du tableau. value_out2(état) Ce mot clé donne la valeur quadratique de l état à la sortie de l'acteur d'une case du tableau. Opérateurs de mise en tableau Le programme de mise en tableau distingue les tableaux par intervalles des tableaux par événements. Les opérateurs contrôlent différemment la mise en tableau quand une variable d'analyse et une variable de classification dans des spécifications de tableau changent simultanément. Les nouvelles valeurs des variables d'analyse sont mises en tableau par l'opérateur interval () avant le changement, et par l'opérateur event () après. L'opérateur par défaut est l'opérateur interval (). C'est l'opérateur de choix en cas d'analyse de variables de durée. Parfois, cependant, on doit faire un dénombrement d'événements selon leur type. La valeur de dénombrement et le type pourraient changer en même temps, auquel cas on devrait utiliser l'opérateur event (). Les opérateurs de mise en tableau sont employés comme les opérateurs de sommation (delta, value_in, etc.) dans les définitions de tableau. Syntaxe tabulation_operator(état ) où il peut s'agir d'un opérateur event ou interval. Si on utilise à la fois des opérateurs de mise en tableau et des opérateurs de sommation, voici la syntaxe proposée : cumulation_operator ( tabulation_operator ( état ) ) 70 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

79 Exemples // l'exemple qui suit ne fait pas partie de l'exemple simple table Person { type * { event ( count ), interval ( duration () ), duration () // même chose que la ligne précédente } }; table Person { type * { delta ( event ( count ) ) } }; Expressions de tableau avec états dérivés Il existe un riche ensemble d'états dérivés pour la production de tableaux. Pour plus de renseignements, se reporter à : «États dérivés associés aux changements d état des acteurs» «États dérivés associés à la durée des états des acteurs» Exemple 3 Ce tableau consiste en une expression qui donne le nombre de personnes qui ont déjà été caractérisées comme gravement handicapées. D'après les résultats, personnes sur ont souffert d'une invalidité grave au moins une fois dans leur vie. Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 71

80 Spécification de tableau table Person X03_SeverelyDisabled // Choix de <<grave handicap>> { { entrances ( dfle, SEVERE_DIS ) // Personnes ayant déjà souffert d'un grave handicap } }; Résultat de tableau Tableau X03_SeverelyDisabled: Choix de «grave handicap» Personnes ayant déjà souffert d'un grave handicap Valeur Personnes ayant déjà souffert d'un grave handicap Exemple 4 Dans cet exemple, nous calculons l'âge moyen de décès de cinq façons différentes pour la population tout entière à l'aide de certaines des fonctions spéciales de Modgen et de la variable spéciale unit. Spécifications de tableau table Person X04_AgeAtDeath // Façons de calculer l'âge au moment du décès { { value_at_entrances (life_status,not_alive,age)// Âge moyen au décès 0 decimals=2 / unit, 72 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

81 value_at_exits ( life_status, ALIVE, age ) // Âge moyen au décès 1 decimals=2 / unit, value_at_transitions (life_status,alive,not_alive,age)//âge moyen au // décès 2 decimals=2 / unit, value_at_changes ( life_status, age ) // Âge moyen au décès 3 decimals=2 / unit, duration ( life_status, ALIVE ) // Âge moyen au décès 4 decimals=2 / unit } }; Résultat de tableau Tableau X04_AgeAtDeath: Façons de calculer l'âge au moment du décès Quantités sélectionnées Valeur Âge moyen au décès Âge moyen au décès Âge moyen au décès Âge moyen au décès Âge moyen au décès Étiquetage d'expressions Chaque expression peut être suivie de l'étiquette (qui commence par //). Si une étiquette n a pas été fournie, Modgen Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 73

82 construira une étiquette dans cette langue en utilisant l étiquette dans cette langue de l état utilisée dans la dimension. Quand l étiquette est fournie, elle peut contenir les chaînes particulières de formatage qui contrôlent la présentation des résultats en tableau. Les voici : decimals= n indique que la valeur de l'expression doit être présentée à n décimales. On peut changer les décimales d'un tableau de façon dynamique, en vue de la visualisation, à l'aide de l'onglet Décimales des propriétés de tableau (pour plus de détails, reportez-vous au Guide de l interface visuelle de Modgen). Si le tableau comporte plus d'une expression dans sa dimension d'analyse, un nombre différent de décimales peut être précisé pour chaque expression. Pour entrer une nouvelle valeur, il suffit de la taper, d'appuyer sur <F2> ou de cliquer deux fois sur la cellule de la grille afin de modifier la valeur existante. scale= [-]m indique que les valeurs de l'expression doivent être multipliées par 10**m. Le signe moins peut précéder m, ce qui désigne une division du résultat par 10**m. Cases vides Il est possible de spécifier des tableaux où des cases demeureront vides (ou à valeur nulle) au terme de la simulation. Dans ce cas, une expression de tableau non définie se présente sous la forme a * (ou une case vide en mode interactif). Exemple 14 Dans cet exemple, le tableau décrit la population féminine de moins de 0 an. L'expression «revenu moyen» est non définie puisque la valeur est nulle pour unit. Spécification de tableau table Person X14_FemalesUnderAge0 [sex==female && age < 0] // Exemple pervers : femmes d'âge inférieur à zéro { { unit, // Personnes earnings / unit // Gains moyens } }; Résultat de tableau 74 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

83 Tableau X14_FemalesUnderAge0: Exemple pervers: femmes d'âge inférieur à zéro Quantités sélectionnées Valeur Personnes 0 Gains moyens * Présentation de statistiques descriptives sur les expressions de tableau On peut produire des erreurs types et des coefficients de variation pour toutes les cases d'un tableau en spécifiant un nombre, n, supérieur à 1 pour le paramètre de contrôle de sous-échantillonnage s. On crée à cette fin n sous-échantillons parallèles pour chaque simulation, puis on calcule les valeurs à partir de ces observations. Dimensions de tableau On spécifie les dimensions d'un tableau par des variables de classification ou des fonctions spéciales, imbriquées ou non, qui donnent des valeurs discrètes. Aucune limite n'est imposée quant au nombre de dimensions d'un tableau. L'astérisque peut entrer dans l'expression du rang global d'un tableau. Pour spécifier une sommation sur une dimension particulière, l'utilisateur peut faire suivre la dimension d'un +. Dimensions de tableau à valeurs constantes pour chaque acteur Ces types de tableau sont les plus faciles à interpréter, chaque acteur étant présent toute sa vie dans une seule case du tableau (homme ou femme, un seul âge de décès, etc.). Exemple 5 Dans ce tableau, nous stratifions le nombre total de personnes en simulation selon leur sexe. La variable spéciale,, est la seule variable d'analyse qui soit spécifiée. La dimension colonne contient la seule variable de classification sex. On notera que a+ suit cette variable, ce qui indique l'existence d'une colonne de sommation pour les deux sexes. Spécification de tableau table Person X05_PersonsByGenderCol // Stratifier les personnes selon le sexe (colonnes) Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 75

84 { { unit // Personnes } * sex+ }; Résultat de tableau Tableau X05_PersonsByGenderCol: Stratifier les personnes selon le sexe (colonnes) Sexe Personnes Féminin Masculin Toutes Personnes Exemple 6 Dans ce tableau, nous stratifions le nombre total de personnes en simulation selon leur sexe avec la dimension ligne. Spécification de tableau table Person X06_PersonsByGenderRow // Stratifier les personnes selon le sexe (rangées) { sex+ * { unit // unité } }; 76 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

85 Résultat du tableau Tableau X06_PersonsByGenderRow: Stratifier les personnes selon le sexe (rangées) unité Sexe unité Féminin 2534 Masculin Toutes Exemple 7 Dans cet exemple, nous présentons l'âge au décès par classe d'âge. La ventilation selon l'âge est définie par AGE_GROUPS. Spécification de tableau table Person X07_PersonsByAgeDeath // Cas stratifié selon l'âge au décès { split (age, AGE_GROUPS )+ // Groupes d'âge au décès * { entrances (life_status,not_alive) // Personnes } }; Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 77

86 Résultat de tableau Tableau X07_PersonsByAgeDeath: Cas stratifiés selon l'âge au décès Personnes Groupes d'âge au décès Personnes (min,20) 83 [20,30) 38 [30,40) 49 [40,50) 118 [50,60) 333 [60,70) 688 [70,80) 1259 [80,max) Toutes Dimensions de tableau aux valeurs variables pour chaque acteur Il y a une foule de variables de classification dont la valeur varie au cours de la vie d'un acteur en simulation. On peut songer, par exemple, à l'âge ou à l'état d'invalidité. Si une telle variable définit une dimension de tableau, un acteur peut être présent dans plusieurs cases de ce tableau pendant sa vie. Ce type de tableau peut être utile, mais il doit être soigneusement spécifié. Exemple 8 Dans cet exemple, la première colonne présente la population selon les cinq groupes d'âge à l'aide de la fonction spéciale split et de la variable spéciale unit. La sommation donne plus de personnes, car chaque personne en simulation incrémente chaque ligne à son passage d'une classe d'âge à l'autre. Ainsi, le tableau décrit les tendances de survie des personnes en simulation. Voici comment on peut en interpréter les résultats : sur ces personnes, ont survécu 78 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

87 jusqu'à leur 20 e anniversaire, jusqu'à leur 30 e, jusqu'à leur 50 e et jusqu'à leur 60 e. On peut aussi voir dans cette colonne le nombre de personnes qui ne soient jamais entrées dans le groupe d'âge correspondant. La deuxième colonne indique le revenu annuel moyen de la population. On se sert de la fonction spéciale duration () en dénominateur pour une bonne estimation des années de vie. Spécification de tableau table Person X08_AvgEarnByAge // Cas et gains moyens par groupe d'âge { split ( age, AGE_GROUPS )+ * // Groupe d'âges { unit, // Personnes earnings / duration () // Gains moyens } }; Résultat de tableau Tableau X08_AvgEarnByAge: Cas et gains moyens par groupe d'âge Quantités sélectionnées Groupe d'âges Personnes Gains moyens (min,20) [20,30) [30,40) [40,50) [50,60) [60,70) Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 79

88 [70,80) [80,max) Toutes Exemple 9 Dans cet exemple, on place la population selon les cinq groupes d'âge à l'aide de la fonction spéciale split. La première colonne du tableau indique le revenu moyen de la population. La deuxième mentionne la valeur cumulée à ce jour du revenu de la population à l'aide de l'opérateur value_in (). Spécification de tableau table Person X09_AvgCumEarnByAge // Gains moyens et cumulatifs par groupe d'âges { split ( age, AGE_GROUPS )+ * //Groupe d'âges { earnings / duration (), // Gains moyens value_in (earnings) / unit // Gains moyens cumulatifs (value_in) }; } Résultat de tableau Tableau X09_AvgCumEarnByAge: Gains moyens et cumulatifs par groupe d'âges Quantités sélectionnées Groupe d'âges Gains moyens Gains moyens cumulatifs 80 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

89 (value_in) (min,20) [20,30) [30,40) [40,50) [50,60) [60,70) [70,80) [80,max) * Toutes À noter que pour chaque tableau déclaré dans un modèle, Modgen crée des états d'acteur internes pour enregistrer les coordonnées de la case courante de l'acteur dans le tableau. La commande index_type contrôle le type C++ utilisé pour représenter ces états. Les valeurs permises pour index_type sont les types C++ signés char, short, int, long et les types intègres C++ non signés uchar, ushort, uint, ulong (unsigned char, unsigned short, unsigned int, unsigned long, respectivement). Si un modèle ne contient pas de commande index_type, le type utilisé est int. La commande index_type pourrait être utile Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 81

90 dans des modèles où la mémoire est importante, comme des modèles «time-based» ayant beaucoup d'acteurs. Le concepteur de modèle et l'utilisateur de modèle sont responsables d'assurer que le nombre maximum de cases dans tous les tableaux sélectionnés ne dépasse pas les bornes du type C++ donné dans la commande index_type. Si plus d'une réitération sont précisées dans le scénario, il faut multiplier le nombre de cases dans un tableau par le nombre de réitérations plus un pour calculer la borne. Exemple : index_type ushort; Filtres de tableau La commande de mise en tableau permet la sélection de sous-ensembles de la population en simulation par des filtres. Cette caractéristique reconnaît le jeu usuel d'opérateurs booléens en C++ : ==, >, >=, <, <=,!=, &&,. Les filtres de tableau contrôlent aussi l'initialisation d'une variable de durée dans les spécifications de tableau. Ainsi, l'utilisateur qui filtre les états d'invalidité et spécifie une variable d'analyse de durée obtiendra des durées commençant à l'entrée dans tel ou tel état d'invalidité. Exemple 10 Dans cet exemple, le tableau présente des données pour la seule population féminine. Spécification de tableau table Person X10_FilterOnFemales [sex==female] // Filtrage des femmes { { unit // Personnes } }; Résultat de tableau Tableau X10_FilterOnFemales: Filtrage des femmes Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

91 Personnes Valeur Personnes Exemple 11 Dans cet exemple, le tableau présente d'une manière erronée l'âge moyen de décès des gens qui ont déjà souffert d'invalidité dans leur vie. L'erreur commise vise à montrer comment les résultats d'une fonction spéciale de durée dépendent des filtres de tableau. Ce que les résultats indiquent en réalité, c'est le nombre moyen d'années passées par quelqu'un dans un état d'invalidité avant sa mort. Spécification de tableau table Person X11_FilterOnDisabled [dfle!=no_dis] // Filtrage des handicapés { { duration ( life_status, ALIVE ) // Âge moyen au décès decimals=2 / unit } }; Résultat de tableau Tableau X11_FilterOnDisabled: Filtrage des handicapés Âge moyen au décès Valeur Âge moyen au décès Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 83

92 Exemple 12 Dans cet exemple, le tableau présente les résultats pour les gens qui ont déjà eu moins de 18 ans et plus de 65 ans. Spécification de tableau table Person X12_PersonsByAge [age<18 age >=65] // Personnes de moins de 18 ans ou de plus de 65 ans { { unit // Personnes } * split (age,age_groupxs)*sex // Groupe d'âges }; Résultat de tableau Tableau X12_PersonsByAge: Personnes de moins de 18 ans ou de plus de 65 ans Sexe Groupe d'âges Féminin Masculin (min,18) [18,65) 0 0 [65,max) Exemple 13 Dans cet exemple, le tableau porte uniquement sur les femmes qui ont déjà eu plus de 18 ans et moins de 65 ans. 84 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

93 Spécification de tableau table Person X13_FemalesByAge [sex==female && (age > 18 && age <=64) ] // Femmes de plus de 18 ans et de moins de 65 ans. { { unit // Personnes } * split (age,age_groupxs)*sex // Groupe d'âges }; Résultat de tableau Tableau X13_FemalesByAge: Femmes de plus de 18 ans et de moins de 65 ans Sexe Groupe d'âges Féminin Masculin (min,18) 0 0 [18,65) [65,max) Poids de cas et mise à l'échelle de population Modgen permet l'emploi de poids de cas pour la mise en tableau. Les poids de cas servent à mettre à l'échelle toutes les quantités du tableau (y compris l'«unité») qui peuvent être additionnées, sauf les quantités de types «min» et «max» (min_value_in, max_delta, etc.). Ces poids sont également utilisés pour la mise à l'échelle de population (la somme des poids de cas est alors utilisée plutôt que le nombre de cas traités). Le poids par défaut d'un cas est 1, mais il peut être Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 85

94 modifié à l'aide de la fonction SetCaseWeight décrite ci-dessous. Chaque cas débute par un poids de 1, qui demeure en vigueur jusqu'à ce que la fonction SetCaseWeight soit appelée. Les poids de cas n'ont aucune utilité pour les modèles temporels (par exemple XEcon). Les fonctions suivantes fournies par Modgen sont utilisées pour récupérer et définir les poids de cas : void SetCaseWeight(double dcaseweight, double dcasesubsampleweight ); void GetCaseWeight(double *pdcaseweight, double *pdcasesubsampleweight ); Un état spécial appelé «actor_weight» est offert pour chaque acteur. L'appel de la fonction SetCaseWeight provoque en outre la définition de la valeur de l'état «actor_weight» pour chaque acteur figurant dans le cas. L'état «actor_weight» peut être déterminé et affiché à l'aide du BioBrowser. Un autre état spécial appelé «actor_subsample_weight» peut être déterminé par le BioBrowser. Cet état équivaut à l'état actor_weight multiplié par le nombre de sous-échantillons. Cet état indique le poids utilisé pour les quantités du souséchantillon (l'état actor_weight est employé pour les quantités totales). La reproduction de cas intéressants (utilisés actuellement dans le modèle POHEM) représente un exemple d'emploi des poids de cas. Mentionnons également l'ajustement de poids de cas dans le cas de rehausser certaines probabilités afin d'augmenter le nombre de cas intéressants. Tableaux invisibles et dépendances entre les tableaux La fonction «hide» est utilisée pour empêcher des tableaux d être visibles dans l interface de modèles, et la fonction «dependency» permet de créer des relations de dépendance entre des tableaux. La syntaxe de ces fonctions est : hide(nom_tableau, {nom_tableau, nom_tableau, }); dependency(nom_tableau1, nom_tableau2, {nom_tableau3, }); Les arguments à la fonction «hide» sont des noms de tableaux ou des noms de groupes de tableaux qui doivent être cachés, séparés par une virgule. (Notons que cette même fonction «hide» peut aussi être utilisée pour cacher des paramètres dans l interface. Toutefois, les paramètres et les tableaux ne peuvent pas être combinés dans un même appel à cette fonction.) L utilisation du nom d un groupe de tableaux équivaut à l utilisation du nom de chaque member du groupe. Le nom d un tableau d utilisateur (défini dans le chapître suivant) peut également être donné en argument.. La fonction «dependency» crée une relation de dépendance entre le premier tableau nommé dans la fonction et les autres tableaux précisés en arguments; c'est-à-dire que le premier tableau dépend des autres tableaux. Le premier tableau nommé peut être un tableau ou un tableau d utilisateur, mais ne peut pas être un groupe de tableaux. Les autres arguments peuvent être des tabelaux, des tableaux d utilisateurs, ou des groupes de tableaux. Ici aussi, l inclusion d un 86 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

95 groupe de tableau équivaut à l inclusion de chaque membre du grouope. Les règles qui suivent s appliquent aux fonctions «hide» et «dependency» : Tableaux d'utilisateur Si un tableau est caché et qu'aucun autre tableau (inclus) ne dépend de lui, alors il ne sera pas inclus dans la simulation. Si un tableau (A) est caché, mais qu'un autre tableau (B) qui est inclus dépend de A, alors A sera inclus (calculé), mais ne figurera pas sur la liste des tableaux, ni dans la base de données, et il sera impossible de l'exporter. Notez qu'il est spécifié que B est inclus. Si l'utilisateur supprime B de la liste des tableaux inclus dans la simulation (en utilisant l'écran «Mise en place»), alors A ne sera pas inclus non plus (règle 1). Un groupe de tableaux sera montré dans le modèle uniquement s'il contient au moins un tableau inclus et non caché. La même règle s'applique aux groupes et aux fichiers de paramètres. Les tableaux d'utilisateur sont confectionnés à partir d'autres tableaux définis dans les fichiers.mpp. Les tableaux d'utilisateur sont plus puissants que les calculs effectués par chiffrier sur des tables de sortie parce qu'ils produisent aussi les erreurs types et les CV. La définition d'un tableau d'utilisateur ressemble à celle d'un tableau ordinaire, à quelques différences près. Le tableau d'utilisateur doit toujours être nommé, il ne contient pas de filtre, il n'est pas lié à un acteur en particulier, il utilise le symbole de classification, de fourchette ou de partition comme dimension de classification, il recourt à des noms pour les expressions de tableau. Les expressions de tableau peuvent renfermer des décimales ou des spécifications d'échelle tout comme dans les tableaux ordinaires. Modgen prend en charge les totaux de dimension dans les tableaux d'utilisateur. Pour demander les totaux de dimension, ajoutez un «+» après le nom de la dimension (comme dans un tableau normal). À la différence des tableaux réguliers, la demande des totaux de dimension n'entraîne que la création d'un espace de stockage (cellules supplémentaires) pour les valeurs totales. Les totaux ne sont pas calculés automatiquement suite à l'ajout d'un «+» au nom de la dimension. La raison est simple : différentes quantités peuvent être stockées dans les tableaux d'utilisateur et l'addition de celles-ci n'est pas toujours logique (par exemple pour les ratios). L'utilisateur peut souhaiter calculer lui-même les totaux s'ils sont plus complexes que de simples sommes. Si les totaux ne sont que les sommes de valeurs de cellule, vous pouvez lancer une nouvelle fonction fournie par Modgen pour calculer tous les totaux de dimension d'un tableau d'utilisateur particulier. Cette fonction s'appelle «TotalSum» et son prototype est le suivant : void TotalSum(const char *sztablename ); La bonne façon d'utiliser la fonction TotalSum consiste à remplir les cellules du tableau d'utilisateur qui ne correspondent Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 87

96 pas aux totaux, puis à appeler la fonction pour calculer les sommes. Une constante Modgen spéciale appelée UNDEF_VALUE est offerte pour tous les modèles. Ainsi, le modélisateur peut indiquer que certaines cellules d'un tableau d'utilisateur contiennent une valeur nulle (aucune donnée) plutôt qu'un zéro. De cette façon, les cellules des tableaux d'utilisateur contiennent au départ une valeur nulle (UNDEF_VALUE). Le modélisateur n'a pas à assigner la valeur UNDEF_VALUE aux cellules qui ne contiennent aucune donnée. En outre, les totaux de dimension contiennent la valeur UNDEF_VALUE si aucune donnée n'est repérée dans l'ensemble de la dimension (sinon les valeurs nulles sont remplacées par des zéros pour le calcul des totaux). Si le tableau d'utilisateur est très grand et très clairsemé (s'il contient de nombreux zéros), vous pouvez réduire la taille de la base de données de sortie en ajoutant le mot-clé «sparse» optionnel à l'instruction «user_table», comme suit : user_table sparse table_name. Les cellules d'un tableau clairsemé qui contiennent des zéros ne sont pas enregistrées dans la base de données de sortie. Voici comment pourrait se présenter un tableau d'utilisateur : user_table ALLPS_Grads // tableau d'essai (regroupe ALLPS et diplômés) { REP_SCHOOL_YEAR //FR Année scolaire * PS_EDLEV //FR Niveau de scolarité * { ENROL_F, GRAD_F, ENROL_M, GRAD_M //FR Inscriptions - féminin //FR Diplômés - féminin //FR Inscriptions - masculin //FR Diplômés - masculin } }; «user_table» est un nouveau mot clé Modgen. Pour remplir les cases du tableau d'utilisateur, le modèle doit recourir à une fonction appelée UserTables. Voici le prototype : void UserTables(); Modgen fournit deux fonctions appelées «GetTableValue» et «SetTableValue» pour manipuler le contenu des tableaux. Voici les prototypes : 88 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

97 double GetTableValue(CString szexprname,... ); void SetTableValue(CString szexprname, double dvalue,... ); Les arguments facultatifs (indiqués par ) représentent les indices des dimensions de classification du tableau. «szexprname» est la chaîne qui précise à la fois le tableau et l'expression de tableau. Elle se compose du nom du tableau suivi d'un point («.») et du nom de l'expression, par exemple; «ALLPS.Expr0». Les expressions du tableau ordinaire sont toujours nommées «Expr0», «Expr1», etc. Les expressions du tableau d'utilisateur sont nommées dans la définition du tableau. La fonction «GetTableValue» peut lire une case d'un tableau ordinaire ou d'un tableau d'utilisateur, et la fonction «SetTableValue» peut uniquement établir la valeur d'une case d'un tableau d'utilisateur (en utilisant dvalue comme nouvelle valeur de la case). Modgen appelle des «UserTables» pour chaque sous-ensemble afin de pouvoir calculer les erreurs types et les coefficients de variation. Il y a aussi deux fonctions fournies par Modgen : «GetUserTableSubSample()» et «GetUserTableReplicate()». Avec ces fonctions, il est possible, à l intérieur de la fonction UserTables d un modèle, de connaître le numéro du souséchantillon ou de la réitération à l intérieur duquel la fonction a été appelée. Voici un exemple de la fonction «UserTables» tiré du modèle LifePaths : void UserTables() { double dvalue; int int nlevel; nyear; for ( nyear = 0; nyear < SIZE( REP_SCHOOL_YEAR ); nyear++ ) { for ( nlevel = 0; nlevel < SIZE( PS_EDLEV ); nlevel++ ) { dvalue = GetTableValue( "ALLPS.Expr0", nyear, nlevel, FEMALE ); SetTableValue( "ALLPS_Grads.ENROL_F", dvalue, nyear, nlevel ); dvalue = GetTableValue( "ALLPS.Expr0", nyear, nlevel, MALE ); SetTableValue( "ALLPS_Grads.ENROL_M", dvalue, nyear, nlevel ); } Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 89

98 } for ( nyear = 0; nyear < SIZE( REP_SCHOOL_YEAR ); nyear++ ) { dvalue = GetTableValue( "Grads.Expr1", nyear, FEMALE ); SetTableValue( "ALLPS_Grads.GRAD_F", dvalue, nyear, PSE_TVOC ); dvalue = GetTableValue( "Grads.Expr1", nyear, MALE ); SetTableValue( "ALLPS_Grads.GRAD_M", dvalue, nyear, PSE_TVOC ); dvalue = GetTableValue( "Grads.Expr2", nyear, FEMALE ); SetTableValue( "ALLPS_Grads.GRAD_F", dvalue, nyear, PSE_PI ); dvalue = GetTableValue( "Grads.Expr2", nyear, MALE ); SetTableValue( "ALLPS_Grads.GRAD_M", dvalue, nyear, PSE_PI ); dvalue = GetTableValue( "Grads.Expr3", nyear, FEMALE ); SetTableValue( "ALLPS_Grads.GRAD_F", dvalue, nyear, PSE_CC ); dvalue = GetTableValue( "Grads.Expr3", nyear, MALE ); SetTableValue( "ALLPS_Grads.GRAD_M", dvalue, nyear, PSE_CC ); dvalue = GetTableValue( "Grads.Expr4", nyear, FEMALE ); SetTableValue( "ALLPS_Grads.GRAD_F", dvalue, nyear, PSE_BA ); dvalue = GetTableValue( "Grads.Expr4", nyear, MALE ); SetTableValue( "ALLPS_Grads.GRAD_M", dvalue, nyear, PSE_BA ); dvalue = GetTableValue( "Grads.Expr5", nyear, FEMALE ); SetTableValue( "ALLPS_Grads.GRAD_F", dvalue, nyear, PSE_MA ); dvalue = GetTableValue( "Grads.Expr5", nyear, MALE ); SetTableValue( "ALLPS_Grads.GRAD_M", dvalue, nyear, PSE_MA ); 90 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

99 dvalue = GetTableValue( "Grads.Expr6", nyear, FEMALE ); SetTableValue( "ALLPS_Grads.GRAD_F", dvalue, nyear, PSE_PHD ); dvalue = GetTableValue( "Grads.Expr6", nyear, MALE ); SetTableValue( "ALLPS_Grads.GRAD_M", dvalue, nyear, PSE_PHD ); } } Tableaux dérivés Les tableaux dérivés représentent une troisième catégorie de tableaux pouvant être générés par Modgen. Cependant, contrairement aux tableaux réguliers et aux tableaux d utilisateurs, les tableaux dérivés sont créés après la fin d une simulation et ne se fait au fur et à mesure pendant la simulation. Puisqu ils sont créés après la fin de la simulation, et parce qu ils sont générés, modifiés ou supprimés à partir de l interface visuelle des modèles, les techniques d utilisation des tableaux dérivés sont décrites dans le Guide de l interface visuelle de Modgen. Toutefois, comme information de base, notons que les tableaux dérivés peuvent être produits afin de calculer la différence ou les ratios entre tableaux. Lorsque les tableaux dérivés sont créés, les informations suivantes doivent être précisées: le nouveau nom du tableau (qui ne doit comprendre que des caractères alphanumériques et des traits de soulignement) la description du nouveau tableau le nom du tableau d origine (nom du tableau existant qui figure dans la base de données de sortie courante) la base de données de référence (une base de données de sortie, habituellement générée par un scénario différent), le tableau de référence (le nom du tableau existant figurant dans la base de données de référence) l algorithme de calcul («Différence entre tableaux» ou «Ratio entre tableaux» Les tableaux d origine et de référence doivent satisfaire certains critères afin de pouvoir être comparés : Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 91

100 ils doivent être générés à partir du même nombre de sous-échantillons (réitérations), le rang doit être identique, la position de dimension d analyse doit être identique, les formes de toutes les dimensions doivent être identiques. Typiquement, les tableaux dérivés sont utilisés pour calculer des différences ou des ratios entre deux tableaux ayant la même définition provenant de deux exécutions différentes et satisfaisant les critères susmentionnés. Les étiquettes des dimensions du tableau d origine seront utilisées. Les définitions de tableaux dérivés sont préservées dans un fichier Access MS nommé <scénario>(ctbl).mdb (p. ex., BASE(CTBL).MDB). Notons que ce fichier n est créé que lorsqu il est nécessaire, ce qui réduit l encombrement de fichiers. De plus, ce fichier n est ouvert que lorsque c est nécessaire, ce qui réduit le risque qu une longue simulation échoue à un moment donné parce que la base de données des tableaux dérivés ne peut pas être ouverte, par exemple à cause d erreurs de réseau. L ouverture d un tableau dérivé donne d abord lieu à la création d une base de données provisoire. Pour les grands tableaux (p. ex., dans le modèle Demand), comme l ouverture peut prendre du temps, l état d avancement est indiqué sur la barre d état (il en est de même lors du rafraîchissement des tableaux à l écran). D autres fenêtres peuvent être ouvertes pour un tableau dérivé (comme pour les tableaux produits durant une exécution du modèle). Le cas échéant, la base de données provisoire existante est réutilisée. Cette base de données provisoire est supprimée lorsque toutes les fenêtres correspondant au tableau dérivé en question sont supprimées. Assurez-vous d avoir suffisamment d espace sur le lecteur provisoire (habituellement C:) avant de créer les tableaux dérivés. Agrégations de tableau des modèles de cellule Dans le cas de modèles de cellule, des agrégations sont offertes pour les fenêtres de tableau. Pour définir une agrégation, définissez d'abord deux classifications, soit une pour la liste détaillée des éléments et une autre qui contient la liste agrégative, par exemple : classification OCCUPATION { //EN Occupation //FR Profession OCC_0012, //EN 0012 Snr Gov't Mgrs&Officials l'admin. publ. //FR 0012 Cadres sup. de OCC_0013, //EN 0013 Snr Mgrs-Fin.,&Bus. Srvc //FR 0013 Cadres sup. - serv. fin., télécomm. et serv. aux entr. OCC_0014, //EN 0014 Snr Mgrs-Hlth, Educ. //FR 0014 Cadres sup. - santé, ens., serv. comm. et soc. 92 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

101 }; classification OCCUPATION3 { //EN Occupation ( 3-digits ) //FR Occupation ( 3- digits ) (F) OCC3_001, //EN 001 Legislators and Senior Management OCC3_011, //EN 011 Administrative Services Managers OCC3_012, //EN 012 Managers in Financial and Business Services }; Puis, l'agrégation peut être définie à l'aide de la syntaxe suivante : aggregation aggregated_classification, detailed_classification { aggregated_item, detailed_item, aggregated_item, detailed_item, aggregated_item, detailed_item }; «aggregation» est un mot-clé Modgen, tandis que «aggregated_classification», «detailed_classification», «aggregated_item» et «detailed_item» se rapportent aux classifications agrégatives et détaillées définies précédemment ainsi qu'à leurs éléments. Précisons qu'il n'y a pas de virgule avant l'accolade de fermeture («}»). Exemple : aggregation OCCUPATION3, OCCUPATION { }; OCC3_001, OCC3_001, OCC3_001, OCC_0012, OCC_0013, OCC_0014, Guide du concepteur de Modgen v Utilisation du programme de mise en tableau pour la présentation des résultats du modèle 93

102 Vous pouvez changer l'agrégation en cours pour la fenêtre de tableau à l'aide de l'onglet Dimension des propriétés de tableau. Il comporte une colonne Agrégations si une ou des dimensions peuvent être agrégées. Pour les dimensions qui peuvent être agrégées, l agrégation courante de la cellule de grille est affichée. Par ailleurs, des boîtes déroulantes s'affichent lorsque la cellule reçoit l'élément d'entrée. Il est alors possible de sélectionner une autre agrégation dans la liste déroulante proposée. 94 Utilisation du programme de mise en tableau pour la présentation des résultats du modèle Guide du concepteur de Modgen v10.1.0

103 Examen individuel de la vie des acteurs Examen de l'historique des acteurs On peut voir le cheminement de vie de chaque cas en simulation par examen visuel, lecture biographique ou présentation des résultats en fichiers textuels ASCII de débogage. Avec ces deux outils, on peut mieux déceler les erreurs algorithmiques du modèle ou étudier des cas particulièrement intéressants par rapport au modèle spécifié. Pour créer l'historique des acteurs, utilisez la commande de suivi dans un fichier.mpp, recompilez le modèle et lancez la simulation en cochant l'option Suivi dans Access MS ou l'option Suivi textuel à la boîte de dialogue Ligne de commande de l'interface visuelle de Modgen. Examinez ensuite la sortie du suivi dans Access MS à l'aide du navigateur biographique de Modgen, dont référence est faite dans un autre guide de l'utilisateur. Examinez le suivi textuel à l'aide de votre éditeur de texte habituel. Le contenu de la base de données de suivi MS Access ainsi que les règles qui prévalent pour la création des données de suivi sont décrits en détail dans le matériel de référence, «Contenu de la base de données de suivi Modgen». Le suivi est coûteux sur le plan de l'espace de stockage et du temps de simulation. Pour des raisons d'efficacité, la base de données de suivi est enregistrée au départ dans le répertoire TEMP, puis elle est copiée à l'emplacement demandé. Avant de tenter de générer un fichier de suivi d'envergure, vérifiez si vous disposez d'espace suffisant sur l'unité temporaire (il s'agit en général de l'unité C; vous pouvez modifier cette définition à l'aide e la variable environnementale TEMP) et sur l'unité de sortie. Commande de suivi L'activation des résultats par cas se fait par commande de suivi Modgen. Une seule définition de suivi est permise pour chaque acteur du modèle. On peut spécifier un filtre pour n'examiner qu'un sous-ensemble des cas en simulation. Ce filtre est une expression logique. Dans les modèles de cas, le filtre peut contenir un filtre définitif facultatif. Le premier Guide du concepteur de Modgen v Examen individuel de la vie des acteurs 95

104 filtre sert à suivre les acteurs dans un état particulier. Le deuxième filtre est utilisé pour suivre les acteurs qui ont déjà été dans un état particulier. Des dispositions devraient généralement être prises pour que les modèles temporels suivent les acteurs à partir d'une seule réitération pour éviter toute confusion éventuelle lors de la visualisation des résultats dans BioBrowser. Voici la syntaxe de cette commande : Syntaxe track actor_name [initial_filter<,final_filter>] { state_or_link,..., state_or_link } ; Modgen permet d utiliser deux mots clés plutôt que d ajouter tous les et liens qui doivent être suivis. Ces mots clés sont «all_derived_states» et «all_base_states». Le premier ajoute tous les états dérivés de l acteur à la base de données de suivi ; le dernier ajoute tous les états simples, à l exclusion d états internes générés reliés aux filtres des tableaux, le mot clé «unit», ou des filtres des ensembles d acteurs Exemple 1 // Cet exemple ne fait pas partie du modèle simpex. Dans cet exemple, // chaque cas d'acteur enfant est enregistré dès qu'il est joint à // un couple de parents. Deux états sont indiquées // pendant la durée de vie simulée de chaque enfant. Il s'agit // du sexe et de la date de naissance de l'enfant. Le lien multiple // à ses parents est également enregistré pour la durée entière de vie // de l'enfant. track Child [!tentative ] { sex, date_of_birth, mlparents }; Exemple 2 96 Examen individuel de la vie des acteurs Guide du concepteur de Modgen v10.1.0

105 // Les deux filtres sont utilisés track Person [dominant && cohort, ever_borrow] { }: Exemple 3 // Deuxième filtre seulement track Person [,ever_borrow] { }; État actor_id et opérateur de modulo (reste) On peut se servir de l état actor_id dans des expressions d'identité ou des filtres. L état indique l'identificateur d'objet. Il permet principalement de suivre un sous-ensemble d'acteurs aux caractéristiques identiques en relation avec l'opérateur de modulo %. Une opération modulo dégage le reste d'une division. La valeur est neutre quand le numérateur est divisible sans reste par le dénominateur. Exemple // L'exemple suivant ne fait pas partie du code de l'exemple simple. // Dans cet exemple, on fait le suivi de chaque 20 e acteur consommateur. // À remarquer l'utilisation de l état actor_id de concert avec l'opérateur // arithmétique modulo. track Consumer [ 0 == actor_id % 20 ] Guide du concepteur de Modgen v Examen individuel de la vie des acteurs 97

106 { savings, last_quantity, last_price, llaststore }; États générés par Modgen pour les tableaux Pour chaque tableau, Modgen génère un état qui met en œuvre l'expression du filtre du tableau et un état qui met en œuvre l'état «unit» (si le tableau utilise «unit»). Ces états possèdent des noms prévisibles qui peuvent être utilisés pour faciliter l'exploration des tableaux en les précisant au moyen de l'énoncé de suivi pour l'exportation dans BioBrowser. Les filtres ont des noms de la forme table_filter_x et des unités de la forme table_unit_x, où X représente le nom du tableau connexe. Il est également possible d'utiliser ces états dans des tableaux successifs, c'est-à-dire des tableaux qui sont produits plus loin dans le module du code source. Leur utilisation est recommandée uniquement pour la mise au point (débogage) et l'exploration. Ils ne devraient pas être utilisés en code de production. L'exemple qui suit illustre l'utilisation de ces états. track Person [ dominant ] { province, region, table_unit_census_counts, table_filter_census_counts }; table Person CENSUS_COUNTS //FR Dénombrement au recensement [ dominant && IntIs_CENSUS_YEAR( year) ] { 98 Examen individuel de la vie des acteurs Guide du concepteur de Modgen v10.1.0

107 census_year+ * { unit, duration() } }; table Person CENSUS_COUNTS_CHECK //FR Débogage du tableau du recensement [ dominant ] { { duration() } * sim_year+ * table_filter_census_counts //FR Filtre pour CENSUS_COUNTS }; Voici les tableaux produits par un modèle d'essai : Tableau : CENSUS_COUNTS Description du tableau : Dénombrement au recensement Données : Valeur Certaines quantités Année de recensement Unit Duration() Total Guide du concepteur de Modgen v Examen individuel de la vie des acteurs 99

108 Tableau : CENSUS_COUNTS_VÉRIFICATION Description du tableau : Débogage du tableau de chiffres du recensement Données : Valeur Filtre pour CENSUS_COUNTS Année de simulation false (faux) True (vrai) Total Examen individuel de la vie des acteurs Guide du concepteur de Modgen v10.1.0

109 Sujets avancés en Modgen Événements Les acteurs évoluent dans le temps grâce à des fonctions d'événement fournies par l'utilisateur. Une fonction d'événement comporte deux parties. La première donne le temps d'attente avant l'événement, à condition qu'aucun autre événement ne se produise avant. La deuxième partie se compose d'éléments codés qui mettent en œuvre l'événement en question en changeant les valeurs des états. La perte d'un emploi est un exemple d'événement. Dans cet exemple, on pourrait utiliser dans la partie «temps d'attente» de la fonction d'événement le risque de perte d'emploi comme une fonction des caractéristiques de l'individu, par exemple, la durée de son emploi actuel. Dans la mise en œuvre de la fonction d'événement, du code établit les états qui décrivent la nouvelle situation de la personne vis-à-vis de l'emploi et son taux de salaire après la perte d'emploi. En analysant les dépendances implicites dans le temps d'attente de toutes les fonctions d'événement, Modgen appelle les diverses fonctions d'événement de temps d'attente et les fonctions de mise en œuvre d'événement afin de faire évoluer les acteurs en simulation dans le temps. Comme on l'a dit ci-avant, le concepteur doit coder deux fonctions C++ qui correspondent à chaque événement du modèle. Tous les éléments du langage C++ peuvent être utilisés dans ces fonctions. Ces deux fonctions sont déclarées dans la définition d'événement qui fait partie de la définition de l'acteur. Syntaxe event time_function, implement_function <, priority_code>; L'élément time_function doit donner le temps absolu de la prochaine occurrence. Optionnellement, la fonction temps peut avoir en argument un pointeur à un «int». Cet argument sera expliqué dans la prochaine section, «Événements avec mémoire». On doit suivre deux règles lorsqu'on code un élément time_function. D'abord, on ne peut pas établir les états de l'acteur, seulement y faire renvoi. En deuxième lieu, on ne peut pas utiliser de pointeur à l'intérieur de ces fonctions. Si ces deux règles ne sont pas respectées, le compilateur Modgen produira des erreurs. L'élément implement_fonction ne comporte généralement aucune règle de codage. Cette fonction ne donne aucun résultat. Optionnellement, elle peut avoir un argument de type «int». Cet argument est expliqué dans la section, Guide du concepteur de Modgen v Sujets avancés en Modgen 101

110 «Événements avec mémoire». L'élément priority_code est facultatif. Lorsqu'il est présent, il doit être un nombre entier s'échelonnant entre 0 et 250 ou, au lieu de cela, on peut utiliser le mot-clé «time_keeping». Le mot-clé «time_keeping», toutefois, ne devrait être utilisé que pour un seul événement dont le but est de maintenir le temps, comme l événement «Clock» du modèle LifePaths ou «Ticker» de certains modèles basées sur le temps. Cette priorité est plus haute que les priorités disponibles aux concepteurs de modèles, mais plus basse que la priorité de l événement pour les états autoprogrammés. En cas d'égalité entre deux événements ou plus, le système vérifie les codes de priorité. Dans un tel cas, le code ayant la priorité la plus élevée est exécuté en premier. Si l'élément priority_code est absent, Modgen attribue un code de priorité de 0 (c.-à-d. la plus faible priorité) à l'événement. Dans le cas d'une égalité entre les priorités, les événements sont exécutés en ordre alphabétique. Dans le cas d'une égalité entre événements du même nom de différents acteurs, l'ordre de création des acteurs est utilisé, ce qui signifie que l'événement du premier acteur créé sera exécuté en premier. Des codes de priorité devraient être assignés aux événements lorsqu'il y a une possibilité d'avoir des événements simultanés. En particulier, les événements «Clock» ou «Ticker» devraient toujours avoir la plus haute priorité, ce qui sera le cas si l événement a été déclaré en utiliasnt le mot clé «time_keeping». Notez également que dans certains cas, il serait plus efficace d'utiliser des crochets d'acteur plutôt que de multiples événements simultanés. Exemple 1 // La ligne suivante paraît dans la définition de l'acteur. // La fonction timeageoneyear estime le temps d'attente avant l'événement. // La fonction AgeOneYear met en œuvre les actions appropriées à l'égard // de l'acteur. Dans notre exemple simple, ils appartiennent à l'acteur // Logement. event timeageoneyearevent, AgeOneYearEvent; Exemple 2 event timeunistartevent, UniStartEvent, 1; event timemonthlyevent, MonthlyEvent; Dans l'exemple ci-avant, en cas d'égalité, le système appliquera d'abord «UniStartEvent» avant «MonthlyEvent» en raison de son code de priorité plus élevé. 102 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

111 Les événements simultanés sont traités comme distincts pendant la tabulation, plutôt que d'être «amalgamés» en un «super-événement» de tabulation, dans lequel les tableaux seraient mis à jour immédiatement avant que le temps ne changeait, plutôt qu'après chaque événement. Ceci signifie que les tableaux sont mis à jour avant que le prochain événement ne soit exécuté, peu importe le temps. Si deux événements surviennent simultanément, les tableaux seront mis à jour deux fois. Notez que les tableaux demeurent insensibles aux changements «intermédiaires» des états qui surviennent durant l'exécution d'un événement. Seules les valeurs des états à la fin de l'exécution d'un événement ont des effets sur les tableaux. Événements avec mémoire Modgen permet aussi d enregistrer dans la fonction «temps» d un événement les données auxiliaires qui peuvent être extraites et utilisées plus tard par la fonction connexe «mise en œuvre» de l événement. Cette capacité peut être utile dans des situations où la période d attente est déterminée en même temps que les particularités dénombrables de la mise en œuvre éventuelle de l événement. À titre d exemple, mentionnons l événement de migration de LifePaths, où un événement potentiel de migration compte une période d attente, ainsi qu une destination associée qui est liée inextricablement à la période d attente. La fonction «temps» d un événement de migration peut enregistrer la destination associée, si bien que celle-ci peut être utilisée par la fonction «mise en œuvre» de la migration si et quand celle-ci a lieu. La capacité d enregistrer et d extraire des données auxiliaires propres à un événement peut être activée selon le besoin pour chaque événement. Pour activer cette capacité pour un événement particulier, les fonctions «temps» et «mise en œuvre» de l événement doivent être codées de sorte qu elles puissent accepter un argument. Plus précisément, la fonction «temps» doit accepter comme argument un pointeur vers un «int» et la fonction «mise en œuvre» doit avoir un argument de type «int». L exemple qui suit illustre le processus. actor Person { event timeclockevent, ClockEvent, 127; }; TIME Person::timeClockEvent(int *pneventinfo) Guide du concepteur de Modgen v Sujets avancés en Modgen 103

112 { // Obtenir l année de la date du prochain coup de gong. int ngongyear = (int) next_gong_time; // Ce qui suit enregistre l année civile du prochain événement d horloge. *pneventinfo = ngongyear; return next_gong_time; } void Person::ClockEvent(int neventinfo) { // Extrait la valeur de ngongyear mémorisée antérieurement. int ngongyear = neventinfo; // Code qui utilise ngongyear. } just_in_time Cette amélioration permet d utiliser un algorithme différent pour avancer le temps qui améliore dramatiquement l efficacité, en particulier pour les modèles de temps qui ont de nombreux acteurs. Dans tous les modèles, le temps avance lorsqu un événement survient. Par défaut, le temps pour tous les acteurs est mis à jour lorsque n importe quel événement survient. Toutefois, avec le mot-clé optionel, just_in_time, le temps est mis à jour seulement pour l acteur pour qui l événement survient, ainsi que pour tout autre acteur touché par l événement, c.-à.- d. dont les états vont changer au cours de l événement.. Pour utiliser cette capacité, le concepteur de modèle doit inclure ce mot-clé dans la déclaration du type de modèle, comme ceci : model_type case_based, just_in_time; model_type time_based, just_in_time; Pour utiliser just_in_time, quelques restrictions sur l utilisation des états mis à jour continuellement doivent être respectées dans le modèle. Un «état mis à jour continuellement» est un état qui entre dans l une des trois catégories suivantes : L état est mis à jour continuellement 104 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

113 L état est dérivé d un état qui est mis à jour continuellement ou d un état qui, lui, est dérivé d un état mis à jour continuellement, etc. L état a le même nom (nom de membre) qu un état d un autre acteur qui entre dans l une des deux catégories précédentes (Modgen produit une liste des états mis à jour continuellement, ainsi que de leur utilisation, dans le fichier d aide des modèles. La liste peut être visualisée en cliquant sur le lien «États continuellement mis à jour et leur dépendances» dans la page d aide de chaque type d acteur contenu dans le modèle.) Les règles suivantes doivent être respectées par le modèle pour pouvoir utiliser just_in_time : L utilisation d états mis à jour continuellement dans les fonctions temps d événement n est pas permise avec just_in_time. Si just_in_time est demandé, alors un état ne peut pas être dérivé d un état mis à jour continuellement d un autre acteur. Exemple : double test = lspouse->age ; ne serait pas permis avec just_in_time mais double test = age; le serait. Ça implique également que les sumover, etc. ne peuvent avoir un état mis à jour continuellement comme argument. Dans les fonctions qui ne sont pas membres d acteurs, la lecture d états mis à jour continuellement n est pas permise avec just_in_time. Si l une des ces règles n est pas respectée, Modgen le détectera durant la compilation et générera un message d erreur. La façon la plus simple de s assurer que le modèle respecte ces règles est d éviter d utiliser des états mis à jour continuellement, excepté comme dimension d analyse d un tableau. Fonctions additionelles concernant les événements ou l avancement du temps dans une boucle secondaire d événements La fonction «GetCurrentEvent» permet au modèle de jeter un coup d œil à l événement actuellement en cours d exécution, et la fonction «GetNextEvent» permet un coup d œil au prochain événement dans la queue (sans qu il ne soit exécuté). Cela peut être utile lors de l implantation d une boucle secondaire d événements, comme celle qui gère la création des époux dans le modèle LifePaths. Ensemble, elles peuvent être utilisées pour déterminer si l événement suivant doit être exécuté dans la boucle secondaire ou si c est le moment de redonner le contrôle à la boucle principale. La fonction «WaitUntilThisActor» permet à Modgen d avancer le temps d un seul acteur dans des modèles qui Guide du concepteur de Modgen v Sujets avancés en Modgen 105

114 n utilisent pas l algorithme «just-in-time». Cela devrait n être utilisé que dans les boucles secondaires d événements, comme celle qui gère la création des époux dans le modèle LifePaths. Le fait d avancer le temps pour tous les acteurs dans une boucle secondaire d événements peut causer des incohérences dans la tabulation si cette fonction n est pas utilisée. Définition et utilisation de crochets de fonction Modgen permet de diviser une fonction d'acteur entre plusieurs fichiers en fournissant des crochets de fonction. Cela est particulièrement utile pour certaines fonctions normales communes à tous les types de modèle comme Start(), Finish(), etc. Divers modules de modèle peuvent avoir à ajouter du code à ces fonctions, ce qu'ils peuvent faire en définissant des crochets de fonction. Un crochet est une fonction membre d'un acteur sans paramètres ni résultats. Le prototype et la définition de ces fonctions sont semblables à ceux des autres fonctions membres. Une définition supplémentaire (définition du crochet) est nécessaire à l'intérieur de la définition de l'acteur. Voici la syntaxe employée : Syntaxe hook HookFrom, HookTo ; HookFrom doit être une fonction membre sans arguments ni résultats et HookTo peut être toute fonction membre ou fonction d'événement autre que la fonction du temps de l'événement. Une fonction peut s'accrocher à plusieurs autres fonctions et vice versa. Voici un exemple tiré du modèle LifePaths : Exemple file: Education.mpp actor Person {... void hook StartEducation(); StartEducation, Start;... }; void Person::StartEducation() { 106 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

115 ); prov_of_study = (PROV_OF_STUDY) min( prov_of_res, SIZE( PROV_OF_STUDY ) - 1 school_year_start = next_year + (TIME) ( / 12.0 ); school_year_end = school_year_start + (TIME) ( 10.0 / 12.0 ); } Si la fonction à laquelle d'autres fonctions sont accrochées a un lieu privilégié où tous les crochets devraient s'insérer, la ligne suivante peut être incluse dans sa définition. Une seule ligne semblable peut exister dans une définition de fonction. IMPLEMENT_HOOK(); S'il n'y a pas IMPLEMENT_HOOK, tous les crochets s'inséreront à la fin de la fonction. Il convient de noter que l'ordre d'intervention des crochets dans l'exécution de cette commande est tout à fait arbitraire. Exemple tiré du modèle LifePaths : void Person::BirthdayEvent() { IMPLEMENT_HOOK(); if ( sex == FEMALE && curtate_age >= MAX( FERT_AGE ) ) { if ( fecundstat == FERTILE fecundstat == POSTPARTUM ) { fecundstat = MENOPAUSE; } } curtate_age ++; } Fonctions et macro-instructions d'exécution Les fonctions C++ d'exécution et les macro-instructions C++ suivantes sont amplement utilisées dans les fonctions de modèle de microsimulation. On peut les utiliser partout dans le code d'application Modgen. Les fonctions suivantes n'appartiennent à aucune catégorie en particulier et sont énumérées par ordre alphabétique. Les autres fonctions sont catégorisées selon l'usage. On présente également à part les macro-instructions d'exécution. Guide du concepteur de Modgen v Sujets avancés en Modgen 107

116 int EmptyDistributions_<nom_de_paramètre>() Modgen génère des fonctions ayant le forme EmptyDistributions_() pour chaque paramètre cumrate. Le concepteur de modèle pourrait utiliser ces fonctions pour identifier des paramètres cumrate comprenant des distributions vides, et prendre des mesures qui s imposent, ex. terminer la simulation ou écrire un message d avertissement avec WriteLogEntry(). La fonction EmptyDistributions_<nom_de_paramètre>() retourne le nombre de distributions vides dans le paramètre cumrate <nom_de_paramètre>. Pour des paramètres cumrate «model_generated», la fonction retourne zéro si on l appelle dans la fonction PreSimulation(), mais elle retournera la bonne valeur si on l appelle dans du code de simulation ou dans UserTables(). int GetThreadNumber(); Cette fonction donne le numéro de fil du fil de simulation courant ( à l'origine 0, c.-à-d. que le premier fil donnera 0, le deuxième fil donnera 1, etc.). Gbool Lookup_<nom_de_paramètre>(long number, int index1,,,,, int indexk, int *dest1,..., int *dest ) Modgen crée des fonctions Lookup_() à chaque paramètre du taux cumrate. On les utilise pour piger dans des distributions de probabilité discrètes données par un paramètre cumrate <nom_de_paramètre>. Les variables index contiennent des valeurs d'indices dans des dimensions non sommatives ( elles doivent être du type int ou classification). Les variables dest sont des variables de destination qui reçoivent les valeurs de dimensions sommatives (elles doivent être du type int). Il n est pas rare que des paramètres cumrate contiennent des distributions vides c est-à-dire des distributions comprenant uniquement des zéros pour des raisons ou structurelles ou d échantillonnage. Afin que les concepteurs de modèles puissent détecter et traiter des distributions vides dans des paramètres cumrate, la fonction Lookup_<nom_de_paramètre>() retourne un valeur true si la distribution demandé n est pas vide, et false si elle est vide. Cela permet aux concepteurs de modèle de traiter une tentative d utiliser une distribution vide dans un modèle pendant la simulation. Note que la fonction Lookup_<nom_de_paramètre>() retournera par les derniers arguments le premier au lieu du dernier des index de la distribution. Exemple : Lookup_CumBirth( RandUniform(), esex, &nyear, &nprov ); double PieceLinearLookup( double dnumber, double *pdxy, int nsize ); ou double PieceLinearLookup( double dnumber, double *pdx, double *pdy, int nsize ); Cette fonction propre à Modgen qu'on utilise dans l'interpolation linéaire se présente sous deux formes : dans les deux cas, «dnumber» est la valeur x qui donne en résultat la valeur y correspondante. Dans le premier cas, pdxy pointe vers le vecteur des paires de valeurs ( x1, y1, x2, y2,... ) et nsize contient la dimension de ce vecteur (c.-à-d. 2 *nombre de paires). Dans le deuxième cas, pdx pointe vers le vecteur de valeurs x (x1, x2,... ), pdh pointe vers le vecteur de valeurs y (y1, y2,... ) et nsize contient la dimension des deux vecteurs (c.-à-d. le nombre de paires). Les points X et Y peuvent 108 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

117 provenir de différents paramètres; dans le cas de paramètres d'une dimension plus élevée, ces points proviendront de la dernière dimension. int sgn(double dvalue ); Donne le signe de dvalue ( -1, 0, 1 ). void SignalCase(); Cette fonction indique à Modgen que le traitement du cas est terminé. Elle actualise la barre d'avancement de la simulation. On devrait l'appeler dans la boucle de cas de la fonction Simulation jusqu'après l'appel de la fonction CaseSimulation. int Split( double dvalue, int ngrp, int npoints, double *pdpointvalues ) Cette fonction divise dvalue selon les groupes définis dans pdpointvalues (pointeur de valeurs double, qui est habituellement un nom de partition). ngrp contient la valeur précédente de groupe (en base 0) et npoints, le nombre de points dans pdpointsvalues. Cette fonction sert normalement en présimulation à initialiser les paramètres créés par le modèle dont la partition constitue une des dimensions. En voici un exemple : nagegroup = Split( nage, nprevgroup, nbreakpoints, COD_AGE_GROUP ); On notera la «S» de «Split». Cette fonction ne peut être utilisée qu'en code de simulation contrairement à la fonction spéciale Modgen de division («s» minuscule pour «split») qui est uniquement employée en définition d'acteur ou de tableau. void StartCase(); Cette fonction indique à Modgen que le cas suivant est sur le point d'entrer en traitement. Elle doit être appelée dans la boucle de cas de la fonction Simulation juste avant l'appel de la fonction CaseSimulation. void TotalSum( const char *sztablename ); Dans le cas des tableaux d'utilisateur, cette fonction sert à insérer la somme dans les colonnes de totaux du tableau. Fonctions qui modifient la fenêtre d'avancement void CalculationProgress(double dpctdone); Dans le cas des modèles de cellule, la mise à jour du déroulement est effectuée par le code du modèle (soit sous la fonction Simulation ou UserTables) lorsque cette fonction est appelée. void ModelExit( const char *szmessage ); Cette fonction sert à quitter sans accroc le modèle lorsque des erreurs sont détectées durant l'exécution. Elle accepte un argument chaîne qui est adjoint à la boîte «Erreurs et avertissements» de la fenêtre Model Run Progress. La sortie du modèle s'effectue sans anomalie (aucune sortie n'est produite en tel cas). CString ModelString(CString szname); ModelString peut être utilisée pour obtenir des chaînes multilingues du modèle. La fonction donnera l'étiquette associée Guide du concepteur de Modgen v Sujets avancés en Modgen 109

118 à la chaîne szname dans le langage de la simulation. La fonction est particulièrement utile avec la fonction ProgressMessage. Exemple string S_GENERATING_SPOUSES; // Production des conjoints sprintf( szmsg, "%s: %ld / %ld", ModelString( "S_GENERATING_SPOUSES" ), lspouseind, SpouseMarketSize ); ProgressMessage( szmsg ); ProgressMessage(const *char); Cette fonction sert à afficher un message dans la fenêtre d'avancement lors de l'exécution d'un modèle, surtout si des inactivités prenant beaucoup de temps se déroulent dans un cas au début de la simulation, par exemple, ProgressMessage("Generating spouses: 20 / 5000"); void TimeReport( double Time ); Met à jour la barre d'avancement de la simulation dans le cas des modèles temporels. Le premier appel à la fonction TimeReport n est utilisé que pour indiquer le temps de départ de la simulation, mais cet appel à TimeReport() est obligatoire. (Cet appel à TimeReport() devrait être placé dans la fonction Simulation() avant la boucle qui contrôle la simulation.) La barre de progrès utilisera le temps donné en argument lors du premier appel à la fonction TimeReport pour calculer le pourcentage de la simulation fait. WarningMsg(const *char); Affiche un message d'avertissement dans la fenêtre d'avancement. Fonctions associées au générateur de nombres aléatoires void GetRandState(CRandState &rrandstate); Cette fonction renvoie, par référence, un ensemble complet de valeurs de départ et d'écarts. double RandLogistic(); Cette fonction produit une variable centrée logistique au moyen de l inverse de la fonction de densité cumulative (F(x) = 1/(1 + exp(-x))). L argument de cette fonction doit être unique, et doit être un nombre entier constant. Si l argument est absent, Modgen modifiera le fichier «.mpp» et assignera un nombre entier disponible comme argument à la fonction. double RandNormal(); Cette fonction produit une variable centrée aléatoire normale. L argument de cette fonction doit être unique, et doit être un nombre entier constant. Si l argument est absent, Modgen modifiera le fichier «.mpp» et assignera un nombre entier disponible comme argument à la fonction. 110 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

119 double RandUniform(); Cette fonction produit un nombre à virgule flottante compris dans la fourchette de 0 à 1. L argument de cette fonction doit être unique, et doit être un nombre entier constant. Si l argument est absent, Modgen modifiera le fichier «.mpp» et assignera un nombre entier disponible comme argument à la fonction. void SelectRegularRandomGenerator(); Cette fonction revient au générateur de nombres aléatoires assigné au cas courant, après qu'il y a eu utilisation de l'un des générateurs particuliers ci-après. void SelectSpecialRandomGenerator1(); void SelectSpecialRandomGenerator2(); Cette fonction permet au modèle d'utiliser différents générateurs de nombres aléatoires pour des activités différentes (p. ex., la production de conjoints). void SetRandAuxState(long lrandseed ); Cette fonction fixe la nouvelle valeur d'amorçage du générateur auxiliaire de nombres aléatoires. void SetRandState(CRandState &rrandstate); Cette fonction définit un ensemble complet de valeurs de départ et d'écarts. void SetRandState(long lseed,bool bresetdeviates = true ); Cette fonction sert à modifier l'état du générateur de nombres aléatoires d'après un seul argument de valeur d'amorçage. Elle peut s'avérer utile pour changer des clones et/ou au moment de l'initialisation d'un cas. Le second argument est facultatif. Par défaut, tous les écarts aléatoires sont réinitialisés : ainsi, aucun écart restant n'est utilisé. Fonctions utilisées pour les poids de cas et la mise à l'échelle de population long GetAllCases(); Renvoie le nombre de cas demandés. int GetCaseSample(); Renvoie le nombre de sous-échantillons associés au cas actuel. int GetDistributedSubSamples(); Retourne le nombre de sous-échantillons qui seront simulées sur la machine actuelle. Si la simulation n'est pas distribuée, ce nombre correspond au nombre total de sous-échantillons spécifié dans les paramètres de contrôle du scénario. Si la simulation est distribuée, ce nombre correspond au nombre de sous-échantillons par ordinateur spécifié dans les paramètres de contrôle du scénario. int GetFirstSample(); Guide du concepteur de Modgen v Sujets avancés en Modgen 111

120 Retourne le numéro du premier sous-échantillon simulé sur la machine. Les sous-échantillons sont numérotés à partir de 0. Si la simulation n'est pas distribuée, le numéro du premier sous-échantillon est toujours 0. Si la simulation est distribuée, ce numéro correspond au numéro de l'esclave multiplié par le nombre de sous-échantillons par ordinateur. Par exemple, s il y a huit sous-échantillons par ordinateur, le numéro du premier sous-échantillon simulé par le premier esclave (esclave 0) est 0, le numéro du premier sous-échantillon simulé par le deuxième esclave (esclave 1) est 8, le numéro du premier sous-échantillon simulé par le troisième esclave (esclave 2) est 16, etc. void GetCaseWeight(double *pdcaseweight, double *pdcasesubsampleweight ); Renvoie le poids du cas ainsi que le poids du sous-échantillon du cas par l'entremise d'arguments de pointeur. long GetPopulation(); Renvoie la population visée par la mise à l'échelle. int GetPopulationScalingRequired(); Retourne true si l utilisateur a coché la case «Échelonnage de la population» du dialogue «Mise en place du scénario» de l interface visuelle, et false sinon. int GetReplicates(); Retourne le nombre de réitérations dans un modèle de temps int GetSubSamples(); Renvoie le nombre de sous-échantillons. long GetSubSampleCases( int nsample ); Renvoie le nombre de cas figurant dans le sous-échantillon précisé. int GetThreads(); Renvoie le nombre de fils de la simulation. void NoteCaseWeight( double dcaseweight, double dsubsampleweight ); Note le poids du cas et du sous-échantillon. Le poids du cas utilisé pour la mise à l'échelle de la population est déterminé de la façon suivante : 1. Le dernier poids fourni par la fonction NoteCaseWeight. 2. Si la fonction NoteCaseWeight n'a pas été appelée, le poids en vigueur à la fin du cas est utilisé. Le poids du sous-échantillon est facultatif. Si le second argument n'est pas employé, le poids du sous-échantillon noté équivaut au poids du cas multiplié par le nombre de sous-échantillons : cette valeur convient dans la plupart des cas. Toutefois, si une valeur non implicite est assignée au poids du sous-échantillon (par exemple dans le cas de l'utilisation de la post-stratification dans le modèle LifePaths) et si le clonage est utilisé, l'appel de la fonction NoteCaseWeight doit préciser deux arguments. void RestoreSubSampleSeeds(); 112 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

121 Rétablit les valeurs de départ de tous les sous-échantillons. void SetCaseWeight( double dcaseweight, double dcasesubsampleweight ); Définit le poids du cas ainsi que le poids du sous-échantillon. void SignalSubSampleCase(int nsample ); Indique (termine) le cas suivant du sous-échantillon précisé. void StartSubSampleCase(int nsample ); Lance le cas suivant du sous-échantillon précisé. Les deux constantes suivantes sont également offertes : MAX_SUBSAMPLES Nombre maximal de sous-échantillons pouvant être utilisés par le modèle (actuellement, ce nombre est de 42). MAX_SUBSAMPLES_PLUS1 MAX_SUBSAMPLES+1 Constante utile pour la création de totaux de sous-échantillon. Fonctions associées à la date et à la durée Modgen fournit plusieurs fonctions qui facilitent le traitement des périodes infra-annuelles de l année civile. Ces fonctions expriment la durée de trois façons distinctes, appelées plus bas «durée selon le modèle», «nombre de jours» et «durée selon le calendrier». La plupart des fonctions décrites à la présente section permettent à l utilisateur de passer d un mode d expression de la durée à un autre. La «durée selon le modèle» est la durée exprimée sous forme de nombre réel continu, où une «année» a une valeur de 1,0. Le «nombre de jours» est un nombre entier de jours. Il précise de façon unique et dénombre de façon séquentielle les jours écoulés à partir d un jour déterminé dans un passé distant. La «durée selon le calendrier» réexprime le jour courant selon l année, le mois et le jour du mois correspondant. Guide du concepteur de Modgen v Sujets avancés en Modgen 113

122 Deux calendriers distincts ont été intégrés dans ces fonctions. Les années du calendrier grégorien, qui varie en longueur de 365 à 366 jours, ne conviennent pas comme unité de mesure. Par «année grégorienne type», nous entendons 365,2524 jours, c est-à-dire la longueur moyenne d une année dans le calendrier grégorien utilisé aujourd hui. L autre calendrier est le calendrier sans année bissextile. Les années y ont une longueur constante de 365 jours, ce qui signifie que le 29 février ne survient jamais. Les deux calendriers sont subdivisés en année, mois et jour du mois. Le jour de la semaine (c est-à-dire lundi à dimanche) est également fourni. Notez que, dans le calendrier grégorien, la partie entière de la durée selon le modèle n est pas nécessairement égale à l année civile correspondante, mais elle en sera toujours fort proche. Par exemple, le 1er janvier 1988 est le jour n o et est associé à une durée selon le modèle de 1987, Dans les fonctions décrites plus bas, notez que le mois de l année, le jour du mois et le jour de la semaine sont exprimés en prenant 0 comme origine. Autrement dit, janvier est le mois 0 de l année et décembre est le mois 11. Pareillement, lundi est le jour 0 et dimanche est le jour 6. Les semaines commencent toujours le lundi. Le premier jour du mois est numéroté 0. Ces fonctions permettent de calculer certaines autres quantités liées à la date. Par exemple, on peut créer un dénombreur à croissance continue de semaines au moyen d une expression comme njours/ 7. Un dénombreur à croissance continue de mois peut être créé au moyen d une expression comme nannéee * 12 + nmois de l année. Fonctions du calendrier grégorien double GregorianDayLength (); Produit la longueur d un jour en «année grégorienne type». Il s agit de l inverse de 365,2524, arrondi comme il convient en fonction de la précision voulue. int GregorianCalendarToDay (int nyear, int nmonthofyear, int ndayofmonth); Produit le nombre de jours associés à une date donnée (année à 4 chiffres, mois de l année [0 à 11] et jour du mois [0 à 30]) du calendrier grégorien. 114 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

123 double GregorianCalendarToTime (int nyear, int nmonthofyear, int ndayofmonth); Produit la durée selon le modèle correspondant à une date donnée (année à 4 chiffres, mois de l année [0 à 11] et jour du mois [0 à 30]) du calendrier grégorien. double GregorianDayToTime (int nday); Convertit un nombre de jours en durée selon le modèle correspondante. bool GregorianIsLeapYear (int nyear); Étant donné l année à 4 chiffres du calendrier grégorien, indique s il s agit d une année bissextile. int GregorianTimeToDay (double dtime); int GregorianTimeToDay (double dtime, *pnisdayboundary); Convertit une durée selon le modèle en un nombre de jours. Toute partie fractionnaire du jour est ignorée. Autrement dit, la durée est arrondie à la baisse au jour le plus proche. Le deuxième argument, qui est optionnel, produit un indicateur qui est fixé à «true» (vrai) si dtime correspond à une borne de jour exacte. Sinon, l indicateur est fixé à «false» (faux). void GregorianDayToCalendar (int nday, int *pnyear, int *pnmonthofyear, int *pndayofmonth, int *pndayofweek); Étant donné un nombre de jours, produit l année, le mois de l année [0 à 11], le jour du mois [0 à 30] et le jour de la semaine [0 à 6] correspondants du calendrier grégorien. void GregorianTimeToCalendar (double dtime, int *pnyear, int *pnmonthofyear, int *pndayofmonth, int *pndayofweek); Étant donné une durée selon le modèle, produit l année, le mois de l année [0 à 11], le jour du mois [0 à 30] et le jour de la semaine [0 à 6] correspondants du calendrier grégorien. Fonctions du calendrier sans année bissextile Guide du concepteur de Modgen v Sujets avancés en Modgen 115

124 double LeaplessDayLength (); Produit la longueur d un jour de l «année type du calendrier sans année bissextile». Il s agit de l inverse de 365, arrondi comme il convient en fonction de la précision souhaitée. int LeaplessCalendarToDay (int nyear, int nmonthofyear, int ndayofmonth); Produit le nombre de jours correspondant à une date donnée (année à 4 chiffres, mois de l année [0 à 11] et jour du mois [0 à 30]) du calendrier sans année bissextile. double LeaplessCalendarToTime (int nyear, int nmonthofyear, int ndayofmonth); Produit la durée selon le modèle correspondant à une date donnée (année à 4 chiffres, mois de l année [0 à 11] et jour du mois [0 à 30]) du calendrier sans année bissextile. double LeaplessDayToTime (int nday); Convertit un nombre de jours en durée correspondante selon le modèle. bool LeaplessIsLeapYear (int nyear); Produit toujours la valeur «true» (vrai). Cette fonction figure dans le modèle uniquement pour que la famille de fonctions du calendrier «sans année bissextile» contiennent une fonction analogue pour chaque membre de la famille de fonctions du calendrier grégorien. int LeaplessTimeToDay (double dtime); int LeaplessTimeToDay (double dtime, *pnisdayboundary); Convertit une durée selon le modèle en un nombre de jours. Toute partie fractionnaire du jour est ignorée. Autrement dit, la durée est arrondie à la baisse au jour le plus proche. Le deuxième argument, qui est optionnel, produit un indicateur qui est fixé à «true» (vrai) si dtime correspond à une borne de jour exact. Sinon, l indicateur est fixé à «false» (faux). void LeaplessDayToCalendar (int nday, int *pnyear, int *pnmonthofyear, int *pndayofmonth, int *pndayofweek); Étant donné un nombre de jours, produit l année, le mois de l année [0 à 11], le jour du mois [0 à 30] et le jour de la semaine [0 à 6] correspondants du calendrier sans année bissextile. 116 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

125 void LeaplessTimeToCalendar (double dtime, int *pnyear, int *pnmonthofyear, int *pndayofmonth, int *pndayofweek); Étant donné une durée selon le modèle, produit l année, le mois de l année [0 à 11], le jour du mois [0 à 30] et le jour de la semaine [0 à 6] correspondants du calendrier sans année bissextile. Fonctions pour des conversions entre nombres entiers et classifications Modgen comprend des fonctions facilitant l utilisation des classifications qui établissent implicitement des concordances avec des valeurs entières. Un sous-ensemble particulier d années ou un sous-ensemble d âges sont des exemples de ce genre de classification. Pour chaque classification comptant au moins un niveau dont le nom se termine par un nombre entier, Modgen créera trois fonctions. Ces fonctions sont nommées IntIs_xxx(entier), IntTo_xxx(entier) et Intfrom_xxx(niveau), où «xxx» est le nom de la classification. Aux fins de ces fonctions, chaque niveau de la classification est associé à une valeur numérique correspondant aux chiffres de droite du nom du niveau. Par exemple, le niveau de classification YR_1991 serait associé au nombre entier La fonction IntIs_xxx(entier) produira «true» (vrai) si le nombre entier correspond à un des niveaux de classification xxx. La fonction IntTo_xxx(entier) produira le niveau de classification xxx qui correspond au nombre entier. Si le nombre entier ne figure pas dans la classification xxx, IntTo_xxx(entier) produira le dernier niveau auquel n est associée aucune valeur numérique (p. ex., YR_NA). S il n existe aucun niveau non numérique de ce genre dans la classification xxx, le dernier niveau de la classification sera produit. Si plusieurs niveaux ont en commun la même valeur entière, le premier de ces niveaux est celui qui sera produit par la fonction. La fonction IntTo_xxx(entier) produit une valeur de type xxx, ce qui signifie qu un moulage de cette valeur n est normalement pas nécessaire. Enfin, la fonction Intfrom_xxx(niveau) convertit un niveau de la classification xxx à la valeur entière correspondante. Si le niveau ne possède aucune valeur numérique associée (p. ex., YR_NA), la fonction produit la valeur 1. L utilisation de ces fonctions est plus facile à comprendre au moyen d exemple. Dans le code qui suit, notez comment la fonction IntIs_CENSUS_YEAR() est utilisée dans le filtre de tableau de sorte que le tableau ne contienne que des années de recensement et comment la fonction IntTo_CENSUS_YEAR() est utilisée pour établir la correspondance entre l état défini en nombre entier «année» et la classification CENSUS_YEAR. classification CENSUS_YEAR { //EN Census Year YR1971, //EN 1971 Guide du concepteur de Modgen v Sujets avancés en Modgen 117

126 YR1976, //EN 1976 YR1981, //EN 1981 YR1986, //EN 1986 YR1991, //EN 1991 YR1996, //EN 1996 YR2001 //EN 2001 }; actor Person { CENSUS_YEAR census_year = IntTo_CENSUS_YEAR( year ); //EN Census Year }; table Person CENSUS_COUNTS //EN Census Counts [ dominant && IntIs_CENSUS_YEAR( year ) ] { census_year * { unit } }; L exemple qui suit montre que l on peut utiliser la fonction Intfrom_ pour produire un tableau en se servant de niveaux choisis à partir d une classification plus grande. classification FOS { //FR Domaine d étude FOS1, //FR Mathématiques FOS2, //FR Économie FOS3, //FR Sociologie FOS4, //FR Anthropologie FOS5, //FR Psychologie 118 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

127 FOS6, //FR Kinésiologie FOS7 //FR Ontologie }; classification FOS_SEL { //FR Domaine d étude (certains) FOS_SEL2, //FR Économie FOS_SEL3, //FR Sociologie FOS_SEL5 //FR Psychologie }; actor Person { FOS fos; //FR Domaine d étude FOS_SEL fos_sel = IntTo_FOS_SEL( Intfrom_FOS( fos ) ); //FR Domaine d étude }; table Person FOS_ALL //FR Diplômés [ dominant ] { fos * { unit } }; table Person FOS_SELECTED //FR Diplômés [ dominant && IntIs_FOS_SEL( Intfrom_FOS( fos ) ) ] { fos_sel * { unit } }; Guide du concepteur de Modgen v Sujets avancés en Modgen 119

128 Macro-instructions d'exécution CASES( ) Cette fonction renvoie le nombre total de cas à simuler par le fil d exécution actuel, lors de l exécution d un modèle de cas. COERCE( range_name, variable_name ) La macro COERCE force une valeur à être comprise entre les limites inférieure et supérieure d une fourchette. Exemple range REP_YEAR70 {1970,1979}; COERCE(REP_YEAR70, year) Si l année est comprise entre 1970 et 1979, la valeur de l année est produite; si elle est inférieure à 1970, la valeur 1970 est produite; et si elle est supérieure à 1979, la valeur 1979 est produite. C est exactement équivalent à (year < MIN(REP_YEAR70))? MIN(REP_YEAR70) : (year > MAX(REP_YEAR70))? MAX(REP_YEAR70) : year; MAX( range_name ) Cette fonction renvoie la valeur maximale de la fourchette. MIN( range_name ) Cette fonction renvoie la valeur minimale de la fourchette. POINTS(partition_name) Cette fonction renvoie les valeurs définissant une partition sous forme d'une matrice de nombres à virgule flottantes. POINTS(partition)[0] donne donc la première valeur dans la partition, POINTS(partition)[1] la deuxième, etc. Exemple : Supposons qu'on définisse la partition suivante : partition AGE_PARTITION //EN Age group { 15, 45, 65 }; Alors POINTS(AGE_PARTITION)[0] est égale à 15, POINTS(AGE_PARTITION)[1] est égale à 45 et POINTS(AGE_PARTITION)[2] est égale à 65. Le code suivant calcule les bornes inférieures et supérieures du groupe d'age nagegroup. 120 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

129 int nagegroup; double dlower; double dupper; // limite inférieure du groupe d âge if ( nagegroup == 0 ) { // set lower to be minimum age (zero) dlower = 0.0; } else { dlower = POINTS(AGE_PARTITION)[nAgeGroup - 1]; } // limite supérieure du groupe d âge if ( nagegroup == SIZE(AGE_PARTITION) - 1 ) { // utilisons l âge maximal dans le modèle comme // limite supérieure dupper = MAX(LIFE_SPAN); } else { dupper = POINTS(AGE_PARTITION)[nAgeGroup]; } À noter que le macro SIZE(partition) donne le nombre d'intervalles dans la partition et non le nombre de points qui définissent la partition. Cela est cohérent avec l'utilisation de SIZE pour des range et des classification : SIZE donne le nombre de valeurs distincts dans le range, classification, ou partition. Le nombre d'intervalles dans une partition est toujours un de plus que le nombre de points définissant la partition. En d'autres mots, le nombre d'éléments dans la matrice POINTS(partition) est toujours égale à SIZE(partition) 1. Parce que les indices des matrices dans C++ commencent toujours à zéro, la valeur maximum permise pour un indice dans la matrice POINTS(partition) est SIZE(partition) 2. RANGE_POS( range_name, variable_name ) Cette fonction convertit les valeurs de fourchette en indices d'origine 0. Cela est particulièrement utile dans l'indexation d'un tableau de paramètres dont l'étendue constitue une des dimensions. RANGE_POS s'occupe aussi des valeurs hors intervalle, les faisant tomber dans l'intervalle ou la fourchette en question. Exemple Guide du concepteur de Modgen v Sujets avancés en Modgen 121

130 // l'exemple suivant n'est pas pris de l'exemple simple range CAL_YEAR { 1899, 1999 }; nyearind = int( current_time ); fte_earnings = 52 * weekly_hours * earn_rate* AvgIndWage[RANGE_POS( CAL_YEAR, nyearind )]; SIMULATION_END() Cette macro-instruction renvoie l'heure lorsque la simulation des modèles temporels se termine (elle commence à l'heure 0). SIZE( symbol ) Cette macro-instruction renvoie la taille de la fourchette, de la classification ou de la partition indiquée par le symbole. SPLIT( dvalue, partition_name ) Partitionne dvalue selon les groupes définis dans partition_name. Cette macro est typiquement utilisée dans la fonction «PreSimulation» pour initialiser les paramètres générés par le modèle qui utilisent une partition comme dimension. Notons que la macro «SPLIT» utilize les mêmes arguments que l état dérivé «split». Cependant, l état dérivé ne peut être utilisé qu à l intérieur de la déclaration d un acteur ou d un tableau. WAIT( wait_time ) Cette macro-instruction convertit le temps d'attente wait_time en un temps absolu WITHIN( range_name, variable_name ) La macro WITHIN produit une valeur logique qui indique si une valeur donnée est comprise entre les limites inférieure et supérieure (inclusivement) d une fourchette donnée. Exemple : range REP_YEAR70 {1970,1979}; WITHIN(REP_YEAR70, year) Le code de la macro WITHIN est exactement équivalent au code suivant : year >= MIN(REP_YEAR70) && year <= MAX(REP_YEAR70); La macro WITHIN peut être utilisée pour simplifier le code du modèle appliqué pour restreindre les totalisation à certaines fourchettes. Par exemple, le code 122 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

131 actor Person { REP_YEAR70 rep_year70 = year; //FR Les années 70 logical rep_year70_filter = year >= MIN(REP_YEAR70) && year <= MAX(REP_YEAR70); }; table Person DECADE70 [ dominant && rep_year70_filter ] { rep_year70 * {unit} }; peut être remplacé par actor Person { REP_YEAR70 rep_year70 = year; //FR Les années 70 }; table Person DECADE70 [ dominant && WITHIN(REP_YEAR70, year) ] { rep_year70 * {unit} }; Accès aux paramètres de modèle dans les fonctions C++ Il y a plusieurs modes d'accès aux paramètres de modèle dans le langage Modgen. Chaque mode est particulier au type de paramètre de modèle. Paramètres, de type numeric L'accès aux paramètre numeric du modèle se fait par simple affectation. Guide du concepteur de Modgen v Sujets avancés en Modgen 123

132 Exemple // l'état, tfem, reçoit la valeur du paramètre de modèle scalaire, // FemaleProp. tfem = FemaleProp; // l'état, esex, reçoit la valeur de zéro // si le nombre aléatoire, RandUniform() est inférieur ou égal à la valeur // de FemaleProp. // l'état, esex, reçoit la valeur de un dans le cas contraire esex = ( RandUniform() <= FemaleProp ) // l'état, z, reçoit une valeur dans la matrice de paramètres // de modèle, ProbMort. La valeur correspond à l'emplacement dans le tableau // défini par la valeur courante de la classification, du sexe et de // l'âge-1 z = ProbMort[sex][age - 1] Paramètres du type cumrate L'accès au paramètre de modèle du type cumrate se fait par la fonction spéciale Lookup_. La section consacrée aux fonctions spéciales décrit la syntaxe de Lookup_. Exemple // les états, Year et Prov, sont définies à condition que le // nombre aléatoire, RandUniform(), soit comparé aux valeurs du paramètre // CumBirth. La comparaison est conditionnelle au sexe de la personne. Lookup_CumBirth( RandUniform(), esex, &nyear, &nprov ); Paramètres du type piece_linear Pour obtenir la valeur d'une fonction piece_linear pour un argument darg, on appelle la fonction spéciale Lookup_. Exemple range WAGE_POINT_VALUES { 0, 7 }; 124 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

133 ... parameters {... piece_linear WagePoints[WAGE_POINT_VALUES] = { 0, 40, 0.3, 85, 0.7, 115, 1, 205 };... }; dlowerwage = Lookup_WagePoints(.33 ); dupperwage = Lookup_WagePoints(.66 ); Dans cet exemple, les valeurs X présentent les probabilités cumulées pour l'intervalle salarial correspondant et les valeurs Y, les valeurs limites de cet intervalle. Dans chaque intervalle, les valeurs salaires sont uniformément réparties. Ainsi, la probabilité est de 0,3 que le salaire se trouve dans l'intervalle [ 40, 85 ], de 0,4 ( 0,7 0,3 ) dans l'intervalle [85, 115] et de 0,3 dans l'intervalle [115, 205]. On peut obtenir les tertiles limites du paramètre WagePoints avec les appels suivants de la fonction Lookup_WagePoints : À noter que la deuxième forme de la fonction PieceLinearLookup représente une méthode d'interpolation linéaire plus souple et d'utilisation préférable. Avec cette méthode, il n'est pas nécessaire de définir un paramètre comme un type piece_linear : vous utilisez simplement les paramètres qui renferment les points X et Y avec appel de fonction à PieceLinearLookup. Paramètres de type file Modgen représente un paramètre de type file comme chaîne C++ (plus spécifiquement par un CString). Un paramètre de type file pourrait être utilisé directement comme argument à une fonction qui prend une chaîne comme argument, ex. la fonction C++ fopen() dans l'exemple en bas. On pourrait avoir accès à la valeur de la chaîne en utilisant le nom directement, comme dans l'exemple qui suit : void PreSimulation() { CString szwork; CString szfilecontents; FILE *fp = fopen( my_file, "r" ); Guide du concepteur de Modgen v Sujets avancés en Modgen 125

134 if ( fp!= NULL ) { char szbuffer[100]; fgets(szbuffer, 100, fp); szwork.format(" my_file=%s\n contents=%s", my_file, szbuffer); } else { szwork.format(" my_file=%s\n Unable to open file", my_file); } } AfxMessageBox(szWork); Quand on tourne la simulation, l'exemple en haut afficherait une boite de message comme celle-ci : Liens entre acteurs : accès d'états entre objets du modèle Souvent dans une simulation de modèle, un acteur doit avoir accès à un état d'un autre acteur. Prenons le simple cas où l'acteur logement doit avoir accès au revenu gagné de l'acteur personne pour le calcul du solde. D'habitude, le concepteur d'applications associera des pointeurs entre structures (ou classes) de données à cette fin. Modgen fournit des liens qui sont essentiellement des pointeurs entre acteurs du modèle. Ils se définissent symétriquement entre acteurs de sorte que Modgen puisse constamment actualiser les liens de dépendance entre les états des divers acteurs. Le système permet aussi que les variables liées définissent une stratification de tableau. C'est pourquoi les tableaux font usage du programme des liens. Comme les types de liens dérivent des pointeurs C++, la déclaration, la définition, l'initialisation et la syntaxe suivent en 126 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

135 gros les conventions C++ relatives à ces membres. Définition des liens Les liens de modèle peuvent unir un acteur à un autre ou à plusieurs autres ou encore plusieurs acteurs à plusieurs autres. Dans tous les cas, les liens réciproques sont automatiquement créés par Modgen. Ainsi, le concepteur d'applications affecte un seul sens de ces liens. Le nom de lien doit être unique pour un même acteur. Le même nom ne saurait servir à deux liaisons distinctes. La définition des liens figure normalement dans la partie du fichier.mpp qui définit les paramètres de modèle. Voici la syntaxe employée : Syntaxe d'un lien un à un link actor_name.link_name ; link actor_name1.link_name1 // étiquette du lien 1 actor_name2.link_name2 // étiquette du lien 2 ; La première définition spécifie un lien entre deux acteurs du même type (actor_name). Dans la deuxième, le actor_name1 doit être différent du actor_name2. Dans le second cas, des étiquettes doivent être associées aux liens. Règle générale, la première lettre qui suit le «.» devrait être un «l» désignant un lien unique. Exemples // À remarquer que ces liens ne paraissent pas dans l'exemple simple // dans le premier exemple, un lien unique entre la personne principale // et son conjoint est établi. // Dans le deuxième exemple, un lien unique est établi entre un conjoint // d'un second mariage et un conjoint auxiliaire link Person.lSpouse; link Person.lSecSpouse // Conjoint // Conjoint d'un second mariage Ancillary.lSpouse; // Conjoint Syntaxe d'un lien un à plusieurs link actor1_name.link_name1 actor_name2.link_name2[]; Guide du concepteur de Modgen v Sujets avancés en Modgen 127

136 Cette définition spécifie un lien entre deux acteurs, le premier étant unique et le second multiple. Règle générale, la première lettre qui suit le «.» pour le premier acteur devrait être une «l» désignant l'unicité, et pour le second acteur un «ml» désignant la multiplicité. Exemples // À remarquer que ces liens ne paraissent pas dans l'exemple simple // un lien est établi entre le conjoint et les enfants link Person.lSpouse Person.mlChildren[ ]; Syntaxe d'un lien plusieurs à plusieurs link actor1_name.link_name1[] actor_name2.link_name2[]; Cette définition spécifie un lien entre deux acteurs multiples. Exemples // À remarquer que ces liens ne paraissent pas dans l'exemple simple // un lien est établi entre les enfants et les parents link Person.mlChildren[ ] Child.mlParents[ ]; Déclaration des liens On déclare les liens comme pointeurs à la manière du C++. La déclaration est la même pour les liens uniques et les liens multiples. Syntaxe Actor_name *practor_name; Exemple // À remarquer que ces liens ne paraissent pas dans l'exemple simple // un lien est établi entre les enfants et les parents 128 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

137 Child *prchild; Person *prdominant; Person *prnondominant; Initialisation des liens L'initialisation des liens suit la convention C++ d'initialisation des pointeurs pour les liens uniques, mais recourt à une fonction spéciale pour l'initialisation des liens multiples. On doit se rappeler que l'acteur et le pointeur doivent tous deux être installés avant l'initialisation du lien. Syntaxe de l'initialisation d'un lien unique link_name = prpointer_name; Exemple // À remarquer que ces liens ne paraissent pas dans l'exemple simple // un lien est initialisé pour le conjoint lspouse = prnondominantperson; Syntaxe de l'initialisation d'un lien multiple link_name->add(prpointer_name); Exemple // À remarquer que ces liens ne paraissent pas dans l'exemple simple // un lien est initialisé pour les enfants mlchildren->add(prchild); Fonctions spéciales agissant sur les liens multiples Ces fonctions spéciales permettent au concepteur d'applications de produire des statistiques sur un ensemble d'objets en liaison multiple. Pour les liens multiples (avec «[ ]»), la syntaxe est l'une des suivantes : Syntaxe multilink_function ( link_name ) Guide du concepteur de Modgen v Sujets avancés en Modgen 129

138 multilink_state_function ( link_name, state_name ) où multilink_function est count - nombre de tous les acteurs liés la fonction multilink_state est une des suivantes : sum_over min_over max_over - sommation de l'état demandé sur tous les acteurs liés - minimum de l'état demandé sur tous les acteurs liés - maximum de l'état demandé sur tous les acteurs liés Exemples actor Household { children = count ( parchild ); age_youngest_child = min_over ( parchild, age ); }; Fonctions d'addition, de soustraction et d'indexation par liaison d'acteurs Pour chaque lien multiple demandé, Modgen définit une classe spéciale comprenant des fonctions membres d'addition, de soustraction et d'itération d'acteurs par les liens. On définit les fonctions suivantes : Add( actor_pointer ) Cette fonction ajoute au lien un acteur du bon type. FinishAll( sans paramètres ni résultats ) Cette fonction appelle la fonction Finish pour tous les objets liés. *GetNext( int ninitpos, int *pnpos ) La fonction *GetNext envoie un pointeur à l'objet disponible suivant par lien multiple en commençant la recherche à la position spécifiée par ninitpos. Elle indique aussi la position de l'élément trouvé. On notera que l'objet en liaison multiple peut ne pas occuper des positions consécutives. Remove( int nposition ) 130 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

139 Cette fonction retire du lien l'acteur à la position spécifiée. RemoveAll() Cette fonction retire tous les acteurs du lien. Exemple de prototype Child *GetNext( int ninitpos, int *pnpos ); Exemple de code de modèle utilisant GetNext // relie la personne principale à l'associé et aux enfants de l'associé lspouse = prnondominant; if ( bfemale ) { prchild = prnondominant->mlchildren->getnext( 0, &nindex ); while ( prchild!= NULL ) { mlchildren->add( prchild ); children++; prchild = prnondominant->mlchildren->getnext( nindex + 1, &nindex ); } } Exemple d'itération par lien multiple : int nindex; nindex = prfamily->parchild->getfirst(); while ( nindex!= -1 ) { prchild = prfamily->parchild->getnext( &nindex ); if ( prchild->active ) { min_time = prchild->nextevent( min_time ); } } Guide du concepteur de Modgen v Sujets avancés en Modgen 131

140 Exemple d'addition par lien multiple : Child *prchild; prchild = prfamily->arallocchildren[nchild]; prchild->start( echildsex, child_birth, sep_age, child_immig ); prfamily->parchild->add( prchild ); Exemple de soustraction par lien multiple : prfamily->parchild->removeall(); La classe de liens multiples n'affecte ni ne désaffecte de pointeurs à des acteurs donnés. Elle travaille seulement sur des pointeurs existants (par les fonctions d'addition, de soustraction et d'indexation). Si un modèle spécifié dans Modgen se propose de réaffecter des pointeurs pour un nombre déterminé d'acteurs, il peut le faire en définissant un jeu de pointeurs dans la définition de l'acteur et en s'en servant. Modgen prédéfinit les types matriciels (ChildArray, PersonArray, etc.) pour chaque acteur. Exemple : actor Household {... ChildArray arallocchildren; // tableau des enfants affectés... } Household::Household() { int nindex;... arallocchildren.setsize( SIZE( CHILD_PAR ) ); for ( nindex = 0; nindex < SIZE( CHILD_PAR ); nindex++ ) { 132 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

141 arallocchildren[nindex] = new Child( this ); }... } TIME Person::ChildBirthEvent( CALL_TYPE ecalltype ) {... nchild = prfamily->children; prchild = prfamily->arallocchildren[nchild]; prchild->start( echildsex, child_birth, sep_age, child_immig ); prfamily->parchild->add( prchild );... } Ensembles d acteurs Un ensemble d acteur est une collection d acteurs maintenue dynamiquement par Modgen. «Maintenue dynamiquement» signifie que Modgen s occupe de l adhésion au groupe selon le critère fourni par le concepteur de modèle. Modgen fournit des fonctions que le concepteur de modèle utilise pour sélectionner aléatoirement un acteur de l ensemble, pour itérer sur tous les membres d un ensemble, etc. Un exemple d un ensemble d acteur est l ensemble d acteurs actuellement susceptibles d infection par une maladie spécifique. Au fur et à mesure que la simulation progresse, les acteurs adhèrent à l ensemble d acteurs à la naissance ou lorsqu ils perdent l immunité maternelle. Ils quittent l ensemble d acteurs en acquerrant l immunité ou à la suite de l infection. Les ensembles d acteurs sont utiles pour les modèles de temps avec plusieurs acteurs ayant des interactions. Les ensembles d acteurs ont été créés pour faciliter le développement de ces modèles en éliminant la nécessité pour le concepteur d écrire du code pour maintenir et manipuler de tels groupes. Modgen maintient dynamiquement les ensembles d acteurs en utilisant des algorithmes internes efficaces et fournit un ensemble clé de fonctions pour exécuter des opérations sur ces groupes de manière efficace. Guide du concepteur de Modgen v Sujets avancés en Modgen 133

142 Voici la liste de propriétés des ensembles d acteurs qui doivent être précisées dans la définition d un ensemble d acteur dans le code du modèle. Voir les exemples qui suivent pour la syntaxe. type d acteur Obligatoire. Un ensemble d acteur contient des acteurs d un seul type, «Person» ou «Dwelling», par exemple, mais il ne contiendra pas les deux types d acteurs dans le même ensemble. nom de l ensemble Obligatoire. Un nom unique qui identifie l ensemble d acteur et permet d appeler les fonctions membres de l ensemble. dimensions filtre Optionnel. Précise un ou plusieurs états ayant un nombre fixe de valeurs possibles (de type «classification», «range», ou «partition») qui divisent l ensemble d acteurs ou sous-ensembles, par exemple par ville. Optionnel. Une expression logique qui définit l appartenance d un acteur à un ensemble d acteurs. (ex. "marital_status == SINGLE"). Semblable au filtre des tableaux de Modgen, mais la syntaxe est légèrement différente. order état ou order RandomStream(nStream) Optionnel. Précise un état dont la valeur est utilisée pour ordonner les membres d un ensemble d acteurs. Modgen maintient automatiquement l ordre au fur et à mesure que la simulation progresse. Lorsque RandomStream est précisé au lieu d un état, un état drandom_xxx est généré pour chaque acteur. Modgen va assigner une valeur à cet état en utilisant RandUniform lorsque l acteur entre dans l ensemble d acteur, ou dans une case d un ensemble d acteurs multidimensionnel. Si la valeur de nstream n est pas précisée, Modgen va générer une valeur unique (nombre entier, comme pour les fonctions existantes RandLogical(), RandNormal(), et RandUniform()). L état drandom_xxx est utilisé pour ordonner les membres de l ensemble d acteurs. Voici des exemples illustrant la syntaxe utilisée pour définir un ensemble d acteurs. actor Person { 134 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

143 }; SEX sex; CITY city; // Sexe // Ville de résidence actor_set Person aseveryone; // Toutes les personnes actor_set Person aseveryonebycity[city]; // Toutes les personnes, en sousensembles par ville actor_set Person assusceptible // Personnes susceptibles d infection filter disease_status!= IMMUNE; order RandomStream(); actor_set Person aseligible[city][sex] // Personnes éligibles pour le mariage filter marital_status!= MARRIED && curtate_age >= 16; actor_set Person aseligibleordered[city][sex] // Personnes éligibles pour le mariage, ordonnées filter marital_status!= MARRIED && curtate_age >= 16 order income; Voici les fonctions qui peuvent être appelées sur un ensemble d acteurs pendant la simulation. Ces fonctions sont implémentées comme fonctions membres d un ensemble d acteurs. Si l ensemble d acteurs est divisé en sous-ensembles, un appel à une de ces fonctions s applique à un sous-ensemble précis. int Count( ) Le nombre d acteurs actuellement membres de l ensemble d acteurs. actor * Item( index ) Retourne l acteur placé à la position index dans l ensemble. index peut avoir une valeur entre 0 et Count( ) 1 inclusivement. Si un nombre flottant est fourni comme valeur de index, seul la partie entière est utilisée. Si une valeur invalide de index est précisée, Item( ) retourne la valeur NULL. La valeur de index associée avec un acteur donné dans l ensemble d acteurs change au fur et à mesure que des acteurs entrent ou quittent l ensemble d acteur. Guide du concepteur de Modgen v Sujets avancés en Modgen 135

144 Les acteurs sont retournés dans l ordre précisé dans la définition de l ensemble d acteurs. Si aucun ordre n a été précisé, les acteurs sont retournés dans un ordre quelconque, mais qui n est pas aléatoire. Pour obtenir les acteurs en ordre aléatoire, il faut préciser RandomStream et appeler la fonction Scramble() avant d itérer avec la fonction Item(). actor * GetRandom( double drandom ) Retourne un acteur au hasard de l ensemble d acteurs. L argument drandom est un nombre aléatoire uniforme, tel que retourné par la fonction RandUniform() de Modgen. Si l ensemble d acteurs ne contient aucun membre, NULL est retourné. Cette fonction est exactement équivalente à l expression Scramble( ) as->item((int)(drandom * as->count()) Fait en sorte que les acteurs de l ensemble d acteurs sont retournés dans un nouvel ordre aléatoire lorsque Item() est appelé. Scramble est disponible seulement pour les ensembles d acteurs dont la définition incluait une clause order RandomStream(). Lorsque appelée, Modgen assigne à chaque acteur une nouvelle position aléatoire dans l ensemble d acteurs (ou dans une case spécifique d un ensemble d acteurs multidimensionnel) Voici des fragments de code illustrant les ensembles d acteurs et leurs fonctions // Choisir un susceptible aléatoire Person *prselected = assusceptible->getrandom(randuniform()); // Nombre de susceptibles dans la population int nsusceptibles = assusceptible->count(); // Itérer sur tous les susceptibles for (int nj=0; nj<nsusceptibles; nj++) { Person *prsusceptible = assusceptibles->item(nj); //... // Faire quelque chose avec prsusceptible //... } 136 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

145 // Sélectionner 10 différents susceptibles au hasard // ce code fonctionne seulement sur un ensemble d acteurs ordonné aléatoirement assusceptibles->scramble(); for (int nj=0; nj<10; nj++) { Person *prsusceptible = assusceptibles->item(nj); //... // Faire quelque chose avec prsusceptible //... } // Nombre d hommes éligibles pour le mariage à Ottawa int neligible = aseligible[ottawa][male]->count(); Notes: Si un ensemble d acteurs est utilisé dans un modèle de cas, il sera vide au début de chaque cas. Les états mis à jour continuellement ne peuvent pas être utilisés dans les ensembles d acteurs, ni comme filtre, ni pour ordonner l ensemble, ni comme dimension. Cela inclus les états dérivés d états mis à jour continuellement ainsi que les états ayant le même nom de membre qu un état mis à jour continuellement d un autre acteur. Si du code qui obtient chaque acteur de l ensemble d acteur en utilisant Item() modifie un état qui affecte l ensemble d acteurs (c est-à-dire soit l ordre, soit le filtre), la boucle peut manquer des acteurs, ou traiter le même acteur plus d une fois. Cela vient du fait que les ensembles d acteurs sont modifiés instantanément lorsque les états y étant associés sont modifiés. Si le concepteur de modèle désire changer de tels états à l intérieur d une boucle, un ensemble d acteurs secondaire peut être utilisée pour contenir les acteurs qui doivent être modifiés. Voici un exemple de comment faire ça : actor Person { }; logical in_holding_area = { FALSE }; actor_set Person asholdingarea filter in_holding_area; Guide du concepteur de Modgen v Sujets avancés en Modgen 137

146 // Placer tous les susceptibles dans l ensemble secondaire int nsusceptibles = assusceptible->count(); for (int nj=0; nj<nsusceptibles; nj++) { Person *prsusceptible = assusceptibles->item(nj); prsusceptible->in_holding_area = TRUE; } // Itérer sur l ensemble secondaire // et vider cet ensemble en même temps Person *prtemp = asholdingarea->item(0); while ( NULL!= prtemp) { // Utiliser prtemp //... // Enlever prtemp de l ensemble secondaire prtemp->in_holding_area = FALSE; prtemp = asholdingarea->item(0); } Voici des exemples supplémentaires: ======================================== // Trouver l homme éligible le plus riche en utilisant un ensemble ordonné int ncount = 0; Person *prrichguy = NULL; // Obtenir le nombre d hommes éligibles dans la ville ncount = aseligibleordered[city][male]->count(); // Obtenir le plus riche prrichguy = aseligibleordered[city][male]->item(ncount - 1); // Obtenir l homme éligible le plus riche en utilisant un ensemble non ordonné int ncount = 0; int nindex = 0; Person *prrichguy = NULL; 138 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

147 Person *prtemp = NULL; // Obtenir nombre d hommes éligibles dans la ville ncount = aseligibleordered[city][male]->count(); // Faire une boucle pour trouver le plus riche for (nindex = 0; nindex < ncount; nindex++) { prtemp = aseligibleordered[city][male]->item(nindex); if (prrichguy == NULL prtemp->income > prrichguy->income) prrichguy = prtemp; } ======================================== // Infecter toute la population de susceptibles Person *prtemp = NULL; prtemp = assusceptible->item(0); while (prtemp!= NULL) { // Modifier l état de maladie. Ça va automatiquement enlever la personne de l ensemble d acteurs prtemp->disease_status = INFECTED; prtemp = assusceptible->item(0); } ======================================== // Faire la liste des 100 entreprises ayant obtenu le plus de profits actor_set Company aseveryone; // Toutes les entreprises order profits;... int ncount = 0; Guide du concepteur de Modgen v Sujets avancés en Modgen 139

148 int nindex = 0; Company *prtemp = 0; // Trouver le nombre d entreprises ncount = aseveryone->count(); //Obtenir les 100 ayant les plus grands profits for (nindex = 1; nindex <= 100; nindex++) { prtemp = aseveryone->item(ncount - nindex); //... // Utiliser prtemp // (ne pas changer les profits!) //... } // NOTE : Toujours, quand on souhaite obtenir les x premiers ou les x derniers, il faut utiliser un ensemble ordonné. Même chose pour la médiane: ================================================ // Obtenir la province avec la médiane la plus haute des revenus individuels classification PROVINCE { //FR Terre-Neuve NFLD, //FR I. P. E. PEI, //FR Nouvelle Écosse NS, //FR Nouveau Brunswick NB, //FR Québec QUE, //FR Ontario //FR Province 140 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

149 }; ONT, //FR Manitoba MAN, //FR Saskatchewan SASK, //FR Alberta ALTA, //FR British Columbia BC, //FR Yukon YUK, //FR T. N. O. NWT actor Person { }; PROVINCE prov_of_res; actor_set Person aseveryonebyprovince[prov_of_res]; //FR Toutes les personnes, en sous-ensembles par province order income;... int ncount = 0; int nindex = 0; int nmedianindex= 0 ; double dpreviousmedian = -1; Person *prtemp = NULL; PROVINCE eprovince = NFLD; PROVINCE elastprovince; for (nindex = 0; nindex < SIZE(PROVINCE); nindex++ ) { eprovince = (PROVINCE) nindex; Guide du concepteur de Modgen v Sujets avancés en Modgen 141

150 ncount = aseveryonebyprovince[eprovince]->count(); nmedianindex = ncount / 2; prtemp = aseveryonebyprovince[eprovince]->item(nmedianindex); if (prtemp->income > dpreviousmedian) { elastprovince = eprovince; dpreviousmedian = prtemp->income; } } //... // Utiliser eprovince //... Moteur de simulation Pour contrôler la simulation, Modgen cherchera les trois fonctions C++ suivantes : PreSimulation cette fonction est facultative. Simulation cette fonction est obligatoire. PostSimulation - cette fonction est facultative. Si elle est présente, la fonction UserTables est également exécutée après la fonction Simulation. Modgen accepte plusieurs définitions des fonctions globales spéciales PreSimulation, PostSimulation et UserTables. Ainsi, des versions différentes peuvent être définies dans des fichiers mpp, si divers modules doivent utiliser un ensemble distinct de paramètres générés par un modèle et/ou de tableaux d'utilisateur. Modgen annote en conséquence le code et appelle les différentes définitions des fonctions spéciales dans l'ordre préconisé lors de leur analyse (il s'agit de l'ordre précisé à la ligne de commande ou de l'ordre du tri de noms dans le cas d'un groupe comportant un caractère générique, comme *.mpp). On doit prendre garde si différentes versions des fonctions spéciales modifient un même paramètre généré par un modèle et/ou un même tableau d'utilisateur. 142 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

151 Fonction PreSimulation Cette fonction est facultative et est exécutée avant la fonction Simulation. On l'utilise le plus souvent pour calculer les paramètres du modèle et initialiser les variables globales (SetMaxTime, etc.). Voici le prototype : void PreSimulation(); Fonction Simulation La principale fonction d'un modèle Modgen est la Simulation(). C'est à ce stade que le nombre de cas passe au moteur de simulation. Dans les modèles de temps, cette fonction doit également appeler «TimeReport()» pour préciser le temps au début de la simulation. Cet appel doit être placé avant la boucle de simulation. La fonction Simulation() appelle respectivement les sous-programmes StartCase(),CaseSimulation() et SignalCase() dans la boucle de simulation, Les fonctions StartCase() et SignalCase() sont internes et ne se trouvent pas dans le code de modèle Modgen. Exemple // ===================================================================== // Fonction principale du modèle de l'exemple simple. // Contient le code nécessaire pour lancer un à un chaque fil de l'exécution. void Simulation() { long lcase; // case loop for (lcase=0;lcase < CASES() &&!gbinterrupted &&!gbcancelled&&!gberrors;lcase++) { // simulation du cas suivant StartCase(); CaseSimulation(); SignalCase(); Guide du concepteur de Modgen v Sujets avancés en Modgen 143

152 } } La fonction CaseSimulation() contrôle la simulation d'un cas. C'est une fonction type en C++ qui ne comporte aucune signification spéciale pour Modgen. Cette fonction crée l'acteur suivant en appelant les fonctions New et Start(), et traite la séquence d'événements par la boucle d'événements. Elle finit l'exercice en libérant tous les acteurs du cas. Les utilisateurs désireux de mieux se renseigner sur la boucle d'événements sont priés de s'adresser à Statistique Canada, à la personne-ressource mentionnée au début du document. Exemple // ===================================================================== // Fonctions de contrôle de la simulation pour le modèle simpex. // Les utilisateurs ne devraient pas modifier le code au-delà de ce point. // Simulation de cas, en l'occurrence un logement dans ce modèle. // Un acteur pour le nouveau cas est créé en même temps que l'acteur personne // lié, une boucle d'événements est exécutée jusqu'au décès de la personne // dans le logement. Les acteurs sont détruits dans leurs fonctions // d'événements respectifs. void CaseSimulation() { // initialisation du pointeur du logement Dwelling *prdwelling; // initialisation du cas suivant ( dwelling ) prdwelling = new Dwelling(); prdwelling->start(); 144 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

153 // boucle d'événements pour le cas actuel while (!gpoeventqueue->empty() ) { ) { if ( gbcancelled gberrors!prdwelling->lperson->life_status == ALIVE // fin du cas et destruction de tous les acteurs gpoeventqueue->finishallactors(); } else { // vieillissement de tous les acteurs jusqu'à l'arrivée de l'événement suivant gpoeventqueue->waituntil( gpoeventqueue->nextevent() ); } // intervention de l'événement suivant gpoeventqueue->implement(); } // libération de la mémoire occupée par les acteurs utilisés dans ce cas DeleteAllDwellingActors(); DeleteAllPersonActors(); } Fonction Postsimulation Les concepteurs de modèles peuvent toujours recourir à une fonction PostSimulation qui est appelée après la simulation mais avant la production des tableaux. On peut l'utiliser pour nettoyer une partie des variables globales et effectuer toute autre activité nécessaire après la simulation. L'utilisation de cette fonction est facultative et Modgen indiquera la version Guide du concepteur de Modgen v Sujets avancés en Modgen 145

154 par défaut si le modèle n'en fournit aucune. Voici le prototype : void PostSimulation(); Construction et initialisation d'acteurs Pour que les spécifications d'un modèle donnent de bons résultats, il est nécessaire de gérer les facteurs de façon intelligente. Chaque acteur d'un modèle doit recevoir une quantité appropriée de mémoire dans laquelle seront entreposés les états, les liens du modèle et tout autre renseignement essentiel. Les acteurs d'un modèle Modgen sont des objets en C++ et ils sont créés et détruits de la façon suivante. On doit construire et initialiser les acteurs au début de la simulation. Il s'agit d'allouer une quantité appropriée de mémoire à un acteur et aux variables appropriées initialisées. Ces deux tâches reviennent respectivement à l'opérateur C++ new et à la fonction spéciale Modgen Start(). Notez que le temps d un nouvel acteur est initialisé au temps actuel de la simulation, à moins qu une valeur n ait été spécifiée dans la fonction «Start». La fonction Start() a une signification spéciale puisque Modgen l'initialise toujours comme une fonction membre (on l'appelle souvent une méthode) d'un objet acteur. Le concepteur du modèle a accès à son prototype par la définition de l'acteur et peut choisir d'y ajouter des arguments. Cela revient à utiliser la fonction Finish() pour la suspension des acteurs. Un acteur ne devrait jamais être utilisé dans le code du modèle après que la fonction «Finish» ait été appelée. Si le code du modèle appelle la fonction «Start» sur un acteur alors que la fonction «Finish» avait déjà été appelée, Modgen affichera une erreur et essaiera de terminer la simulation. Exemple // initialisation du cas suivant ( dwelling ) prdwelling = new Dwelling(); prdwelling->start(); où la fonction Start() se présente ainsi : // Initialisation d'un nouveau logement void Dwelling::Start() { Person *prperson; 146 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

155 // initialisation de la personne suivante prperson = new Person(); prperson->start(); lperson = prperson; } Suspension et destruction d'acteurs La suspension et la destruction de tous les acteurs reviennent respectivement aux fonctions spéciales Modgen FinishAllActors() et DeleteAllActor_nameActors(). L'utilisateur peut spécifier la fonction Finish, mais le concepteur d'applications ne devrait jamais modifier la fonction Delete. Notons qu avec l algorithme «just-in-time», le temps des acteurs doit être ramené au temps actuel avant que ces derniers soient détruits. Cela est fait automatiquement dans la fonction «FinishAllActors».. Contrôle de la précision dans les modèles temporels continus de cas Certaines anomalies peuvent survenir dans les modèles temporels continus à cause de l imprécision du temps et des erreurs liées à l arrondissement. Modgen offre au modélisateur deux façons de contrôler la précision des calculs avec virgule flottante. Utilisation de SetMaxTime pour contrôler la précision Le modélisateur a la possibilité d évaluer la durée maximale de la simulation (la variable time) après quoi Modgen s occupera d arrondir toutes les durées des événements ainsi que la variable age au degré approprié de précision. Cette étape est nécessaire pour des modèles de cas, ainsi que pour des modèles temporels. Cela permettra d éliminer certaines anomalies observées, notamment la valeur de l «âge» au 61 e anniversaire de la personne sera 61 ans exactement et non pas quelque chose du genre L endroit idéal pour évaluer la durée maximale de la simulation est la fonction PreSimulation, qui est appelée une fois seulement avant le début de la simulation. On doit utiliser ici la fonction de Modgen intitulée SetMaxTime. Voici le prototype : void SetMaxTime(double dmaxvalue); Pour les modèles de cas, on pourrait ajouter la ligne suivante à la fonction PreSimulation : Guide du concepteur de Modgen v Sujets avancés en Modgen 147

156 SetMaxTime( MAX( YEAR ) + MaxLife ); Utilisation de CoarsenMantissa pour contrôler la précision Il y a d autres cas où l on peut vouloir contrôler la précision des variables à virgule flottante, pour s assurer que les opérations arithmétiques sur «time» et «age» sont exécutées de façon cohérentes. Pour ce faire, Modgen offre une autre fonction intitulée CoarsenMantissa. Voici le prototype : double CoarsenMantissa(double dvalue, double dmaxvalue); La fonction calcule la valeur arrondie en fonction de la valeur maximale absolue de la variable. Le deuxième argument est facultatif; s il n est pas indiqué, le système utilise ici la valeur établie par la fonction SetMaxtime. «CoarsenMantissa» utilise les valeurs précisées dans l appel précédent à la fonction «SetMaxTime» pour limiter délibérément la précision de tous les temps d attentes, de même que des valeurs de départ de «age» et de «time». En fait, les opérations internes reliées à «time» et «age» sont exécutées avec une précision fixe plutôt qu avec une précision flottante, même si «time» et «age» sont des quantités à virgule flottante. Cela implique une unité minimale de temps indivisible atomique. Cette valeur de temps minimal indivisible atomique peut être obtenue avec la fonction «GetMinimumTimeIncrement». Cette valeur dépend de l argument fourni lors de l appel à la fonction «SetMaxTime» et dépend de la déclaration de «time_type» comme «float» ou «double». La valeur de retour de «CoarsenMantissa» et «GetMinimumTimeIncrement» est de type «double» si «time_type» est déclaré comme «double», alors que si «time_type» est «float», Modgen utilise les versions dont la valeur de retour est de type «float». Voici un exemple de «CoarsenMantissa» tiré du modèle LifePaths : birth = CoarsenMantissa( birth ); Flots indépendants de nombres aléatoires dans les modèles Modgen Modgen utilise des flots indépendants de nombres aléatoires afin d'éliminer les «bruits parasites» et de réduire l'importance des différences entre les exécutions. Lorsque Modgen vérifie les fichiers mpp, il recherche les instructions d'appel des fonctions RandUniform() et RandNormal() qui ne comportent aucun argument, puis il assigne un numéro d'index unique à titre d'argument de ces fonctions. Ces changements sont reportés dans les fichiers mpp avant que les fichiers cpp correspondants soient générés. 148 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

157 Les arguments adjoints par Modgen aux appels de fonction RandUniform() et RandNormal() sont utilisés à l'interne pour garantir l'indépendance de tous les flots de nombres aléatoires employés par le modèle. Par exemple, nous présentons le code suivant (tiré du modèle Simpex) : sex = ( RandUniform() <= FemaleProp )? FEMALE : MALE; est changé en faveur de : sex = ( RandUniform(3) <= FemaleProp )? FEMALE : MALE; Lorsque le modélisateur écrit un nouveau code (par exemple s'il ajoute une nouvelle équation ou un nouvel événement), les appels des fonctions RandUniform() et/ou RandNormal() ne doivent comporter aucun argument. Modgen assigne ces arguments au moment de l'analyse. Modgen ne modifie pas les appels des fonctions RandUniform() et RandNormal() qui comprennent déjà un argument numérique, à moins que des doubles soient repérés (par exemple suite à la copie, par l'utilisateur, d'un bloc de code contenant des appels indexés de la fonction RandUniform). En cas de présence de doubles, les arguments de la fonction sont changés en faveur de nombres uniques. L'état du générateur de nombres aléatoires doit être en mesure de déterminer les valeurs de départ et les écarts de tous les flots de nombres aléatoires utilisés dans un modèle. Pour simplifier l'emploi de l'état du générateur de nombres aléatoires, on doit se servir d'une classe définie par Modgen appelée CRandState. On peut déclarer les variables de type CRandState dans n'importe quelle fonction du modèle, puis les passer à titre d'arguments aux fonctions GetRandState et SetRandState. En outre, la classe prend en charge l'assignation d'une variable CRandState à une autre variable. Dans le cas fort peu probable que des changements s'avèrent nécessaires aux valeurs de départ de quelques flots de nombres aléatoires, on peut manipuler les membres plseeds et pddeviates directement (par exemple plseeds[5] = lnewseed;). Voici la déclaration de la classe CrandState : class CRandState { public: CRandState(); ~CRandState(); void operator=( const CRandState &Other ); }; long *plseeds; double *pddeviates; Guide du concepteur de Modgen v Sujets avancés en Modgen 149

158 Les prototypes des fonctions GetRandState et SetRandState sont présentés ci-dessous : void GetRandState( CRandState &rrandstate ); void SetRandState( CRandState &rrandstate ); void SetRandState( long lseed, bool bresetdeviates = true ); Les deux premiers prototypes des fonctions servent à récupérer et à définir l'ensemble complet de valeurs de départ et d'écarts. Le dernier prototype est utilisé pour modifier l'état du générateur de nombres aléatoires d'après un seul argument de valeur d'amorçage. Il peut s'avérer utile pour changer des clones et/ou au moment de l'initialisation d'un cas. Le second argument est facultatif pour ce prototype. Par défaut, tous les écarts aléatoires sont réinitialisés : ainsi, aucun écart restant n'est employé. Le bloc de code suivant est un exemple d'utilisation des fonctions GetRandState et SetRandState : void CaseSimulation() { CRandState rrandstate; int CloneNumber = 0; int nclonesrequested = 0; while ( nclonenumber <= nclonesrequested ) { if ( nclonenumber == 0 ) { GetRandState( rrandstate ); } else { SetRandState( rrandstate ); } } } 150 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

159 Exécutions réparties Les modèles de cas, ou les reiterations des modèles de temps, peuvent être distributes à travers des machines d un réseau. Si un scenario d une simulation distribuée est utilise, les modèles Modgen utilisent automatiquement le pool de l instance de l application Executor qui tourney sur la machine. Exécutions réparties, tâches principale et auxiliaires Les rôles des tâches principale et auxiliaires lors d une exécution répartie sont les suivants. Lorsqu une exécution répartie est lancée, la tâche principale crée les tâches auxiliaires. Puis, une fois ces tâches créées, elle devient une tâche «auxiliaire» ordinaire. Comme toutes les autres tâches auxiliaires, elle s exécutera puis quittera. Avant de terminer son exécution, une tâche auxiliaire vérifie si elle représente la dernière tâche qui doit être exécutée. Si toutes les autres tâches auxiliaires ont été achevées, elle devient la nouvelle tâche principale. Celle-ci réassemble les données et supprime les tâches auxiliaires de la base de données des demandes. Par conséquent, désormais, une tâche auxiliaire pourra être resoumise de façon indépendante. Si l exécution d une seule tâche auxiliaire échoue, par exemple, l utilisateur peut soumettre de nouveau cette tâche particulière. Si elle est alors exécutée avec succès, elle deviendra la nouvelle tâche principale et réassemblera les données. Durée chronométrée prévue et maximale lors des exécutions réparties On considère que la durée chronométrée maximale ou prévue d une exécution répartie est égale au temps maximal ou prévu nécessaire pour que l exécution d une tâche auxiliaire soit achevée. Par exemple, si l utilisateur fixe la durée chronométrée maximale à 20 heures, l exécution de chaque tâche auxiliaire peut prendre jusqu à 20 heures. Fichiers de journalisations des esclaves fusionnés À la fin de la simulation, les fichiers de journalisation des esclaves seront fusionnés en un fichier de journalisation avec le nom <nom_scénario>(log).txt. Les fichiers de journalisation individuels des esclaves seront détruits. Amélioration: Assemblage des exécutions des esclaves Normalement, les résultats des esclaves d une simulation distribuée sont assemblés automatiquement par Modgen. En cas d erreur, les résultats des esclaves peuvent être assemblés à la main en utilisant une option de ligne de commande. Cette option marche seulement si tout les fichiers des esclaves sont présents. Le syntaxe est comme suit : Guide du concepteur de Modgen v Sujets avancés en Modgen 151

160 model_name -sc scenario_file -SLAVE ASSEMBLE Délibérément, cette option ne touche pas à la base de données d Executor, alors les enregistrements d Executor reliés à la job reste tel quels. Toute action normalement faite par la dernière esclave à part la simulation elle même est faite. Quand cette option est utilisée, le fichier log est nommé <scénario>_assemble(log).txt. Clonage d'observations : Technique particulière Le clonage vise à obtenir un dénombrement plus élevé de la population visée puis à appliquer différents algorithmes (p. ex., des interventions sur des patients souffrant d'un cancer du poumon dans POHEM) sur différents clones du même objet. Même si le clonage ne fait pas partie de Modgen, on peut facilement l'appliquer dans les modèles générés par Modgen. On peut aussi utiliser le clonage pour des totalisations rétrospectives (p. ex., mise en tableau du nombre de débiteurs en défaut selon l'année de leur première entrée dans le système d'études postsecondaires), ce qui ne serait pas toujours possible en recourant à des filtres ou à une totalisation au moment du décès. Dans ce cas, on produit habituellement deux clones du même objet puis on calcule la totalisation sur le deuxième clone (en utilisant une partie des renseignements obtenus pendant la vie du premier clone). Voici le code nécessaire à l'application du clonage dans les modèles LifePaths et Pohem. Les deux états suivants sont ajoutés à l'acteur personne : int CloneNumber; int ClonesRequested; // nombre de clones // nombre requis de clones Il n'y a qu'une seule affectation de la variable CloneNumber (au début de la vie de l'acteur personne, il y a appel de la fonction Start peu de temps après). L'état de la variable ClonesRequested est initialisé à 0 et assigné pendant la simulation s'il se produit un événement d'intérêt. Le clonage s'effectue dans la partie suivante du sous-programme CaseSimulation : void CaseSimulation() { CRandState rrandstate; int nclonenumber = 0; 152 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

161 int nclonesrequested = 0; Person *prdominant; while ( nclonenumber <= nclonesrequested ) { if ( nclonenumber == 0 ) { GetRandState( rrandstate ); } else { SetRandState( rrandstate ); } prdominant = new Person(); prdominant->start( ); prdominant->clonenumber = nclonenumber; prdominant->clonesrequested = nclonesrequested; // boucle d'événements pour le cas courant } nclonenumber = prdominant->clonenumber + 1; nclonesrequested = prdominant->clonesrequested; } Au début de chaque cas simulé, la variable CloneNumber est fixée à 0 et ClonesRequested à 0. Si le code de modèle fixe ClonesRequested pour l'acteur personne principal a une valeur autre que zéro, il y a resimulation du cas traité à l'aide de la même valeur d'amorçage. Cette nouvelle simulation incrémente le compteur CloneNumber. On peut rendre le code de Guide du concepteur de Modgen v Sujets avancés en Modgen 153

162 modèle et les tableaux sensibles à ce compteur afin de multiplier les essais pour un même cas et de décrire leurs effets. Contrôle des modèles précompilés à partir d'applications externes On peut utiliser des applications externes pour contrôler des modèles précompilés Modgen et pour manipuler leurs entrées et sorties. Ainsi, on utilisera cette fonction pour appliquer des techniques de suivi aux fins de l'étalonnage du modèle. En pareil cas, une application de contrôle exécute le modèle dans une boucle et cherche dans l'espace des paramètres du modèle les correspondances avec les totaux de contrôle historiques. Grâce à cette fonction de contrôle, le concepteur de modèles pourra programmer une interface visuelle simplifiée afin de rendre un modèle plus accessible à un auditoire plus vaste. Même si l'option interactive de Modgen offre une interface visuelle générique pour un modèle, une interface visuelle plus simple pourra présenter des écrans spéciaux d'entrée multiparamétriques et effectuer une manipulation plus poussée des sorties du modèle. Modgen comme serveur automatisé en cours Étant donné que la lecture (analyse syntaxique) et l'écriture des fichiers.dat représentent l'une des tâches les plus difficiles d'une telle application, les concepteurs d'applications peuvent accéder à une telle fonction sous forme de serveur automatisé en cours, grâce à la bibliothèque ModAuto10.dll. Il faut enregistrer cette bibliothèque avant de pouvoir utiliser le serveur. Le programme de configuration Modgen effectuera l'enregistrement nécessaire. Pour procéder à un nouvel enregistrement plus tard, utilisez le programme utilitaire de Microsoft appelé regsvr32.exe. On ne peut enregistrer qu'un serveur Modgen à la fois. Si vous avez plusieurs versions du fichier ModAuto10.dll, assurez-vous d'avoir enregistré la bonne version en dernier. Modgen10.AutoParser est l'identificateur programmatique du serveur. Les applications utiliseront cet identificateur pour créer l'objet serveur. Pour plus de renseignements, se reporter à la documentation OLE de votre programme d'élaboration. On doit utiliser cet identificateur pour établir un lien tardif avec le serveur, par exemple Set objparser = CreateObject("Modgen10.AutoParser") 'lien tardif Pour un lien hâtif, on doit utiliser autolib2.autoparser, par exemple Public gobjparser As autolib2.autoparser 'lien hâtif Le programme de configuration de Modgen comporte aussi le fichier de la bibliothèque de types auto.tlb («ModAuto10.tlb»). Les applications peuvent recourir à ce fichier avec les visualisateurs d'objet pour avoir accès à l'information sur les méthodes exposées. Méthodes exposées par le serveur d'analyse et syntaxe employée 154 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

163 Toutes les méthodes donnent un code de résultat (0 signifiant la réussite). On peut trouver les codes d'erreur et leur description dans la base de données de la documentation générée par le modèle. Pour plus de renseignements sur la base de documentation, se reporter au «Contenu de la base de données de documentation Modgen». [id(1)] short Init( BSTR szdocdb ); Initialise le serveur automatisé pour un modèle spécifique à l'aide de l'information enregistrée dans le fichier de la base de données de la documentation szdocdb. [id(2)] short ResetData(); Réinitialise tous les paramètres. On devrait utiliser cette méthode si les fichiers de données doivent être réanalysés. [id(3)] short ReadFiles( BSTR szfilespec ); Analyse le ou les fichiers indiqués par szfilespec ( caractères génériques acceptés ). [id(4)] short SaveFiles( BSTR szfilespec ); Sauvegarde le contenu des fichiers indiqués par szfilespec. [id(5)] short GetParameterCell( BSTR szname, long lcell, VARIANT *pvariant ); Obtient la valeur de données (sous forme d'une chaîne) pour la case lcell ( index linéarisé par ordre d'affichage) pour le paramètre indiqué par szname. La valeur est renvoyée sous forme d'une chaîne dans pvariant. [id(6)] short SetParameterCell( BSTR szname, long lcell, BSTR szdata ); Établit la valeur de données (sous forme d'une chaîne) pour la case lcell ( index linéarisé par ordre d'affichage) pour le paramètre indiqué par szname. szdata renferme la nouvelle valeur. [id(7)] short GetStoredParameterSlices( BSTR szname, long *plslices ); Obtient le nombre de tranches de première dimension entreposées pour un paramètre extensible indiqué par szname. [id(8)] short SetStoredParameterSlices( BSTR szname, long lslices ); Met à jour le nombre de tranches de première dimension entreposées pour un paramètre extensible indiqué par szname. [id(9)] short ParameterUpdateRequired( BSTR szname, short *pnupdate ); Vérifie si un paramètre extensible a besoin d'être mis à jour. Le résultat est renvoyé dans la variable vers laquelle pointe pnupdate ( 1 si une mise à jour est nécessaire, 0 dans les autres cas ). [id(10)] short GetFileNote( BSTR szfile, short nlang, VARIANT *pvariant ); Obtient la note associée au fichier indiqué par szfile dans la langue nlang ( index des langues en base 0 ). [id(11)] short SetFileNote( BSTR szfile, short nlang, BSTR sznote ); Établit la note associée au fichier indiqué par szfile dans la langue nlang ( index des langues en base 0 ). [id(12)] short GetParameterNote( BSTR szname, short nlang, VARIANT *pvariant ); Obtient la note associée avec le paramètre indiqué par szname dans la langue nlang ( index des langues en base 0 ). Guide du concepteur de Modgen v Sujets avancés en Modgen 155

164 [id(13)] short SetParameterNote( BSTR szname, short nlang, BSTR sznote ); Établit la note associée avec le paramètre indiqué par szname dans la langue nlang ( index des langues en base 0 ). [id(14)] short ChangeFileReference( BSTR szoldfile, BSTR sznewfile ); On devrait utiliser cette méthode si un fichier de données est analysé et qu'il doit ensuite être sauvegardé sous un nom différent. Le serveur peut uniquement sauvegarder des fichiers qui ont été traités par l'analyseur syntaxique. Chaque objet (paramètre, exclusion de tableau, note de fichier, etc.) est associé à un fichier, de sorte que le serveur connaît les objets qui doivent être sauvegardés au moment de sauvegarder un fichier de données. Si on utilise la méthode SaverFiles avec un nouveau nom de fichier, un fichier vierge sera créé. La méthode ChangeFileReference permet de résoudre ce problème. On devrait l'appeler tout juste avant la méthode SaveFiles. Elle crée un fichier vide comme effet secondaire, SaveFiles, puis y ajoute un contenu. szoldfile est le fichier original analysé par le serveur, sznewfile est le nouveau nom du fichier. [id(15)] short GetParameterDecimals( BSTR szname, short *pndecimals ); Obtient le nombre de décimales entreposées pour le paramètre indiqué par szname ( une valeur négative dans pndecimals ou ndecimals signifie qu'il n'y a aucune limite). [id(16)] short SetParameterDecimals( BSTR szname, short ndecimals ); Cette méthode permet d'obtenir et de mettre à jour le nombre de décimales entreposées pour le paramètre indiqué par szname (une valeur négative dans pndecimals ou ndecimals signifie qu'il n'y a aucune limite). Modèle de code en VB illustrant l'utilisation du serveur Modgen pour analyser des fichiers.dat Private Sub cmdparser_click() Dim objparser As Object, intret As Integer, pvariant As Variant, i As Long Dim strarray() As String 'lancer le serveur OLE (nécessite une installation de Modgen pour qu'il y ait enregistrement ' du serveur). ' Ajouter aussi un renvoi à auto.tlb en utilisant Tools/References dans VB Set objparser = CreateObject("Modgen.AutoParser2") 'lien tardif ' initialiser le serveur pour votre modèle 156 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

165 (doit d'abord créer le doc DB intret = objparser.init("e:\oletest\lpaths_doc.mdb") ' analyser un ou plusieurs fichiers du type.dat ' vérifier le code de retour intret si on le désire... intret = objparser.readfiles("e:\oletest\loans.dat") ReDim strarray(17984) 'lit un très gros param (une case à la fois, par ordre d'affichage) For i = 0 To 'vous pouvez obtenir le nombre de points de données pour n'importe quel param de la BD de la doc intret = objparser.getparametercell("unituitionfees", i, pvariant) strarray(i) = CStr(pVariant) 'ou convertir à une représentation numérique selon le cas Next i ' modifier la valeur d'un paramètre (celui-ci n'a qu'un point de données) intret = objparser.setparametercell("loandisboption", 0, "LDO_NA") ' sauvegarder le fichier de type.dat ailleurs intret = objparser.changefilereference("e:\oletest\loans.dat", "e:\oletest\myscenarios\scenario1.dat") intret = objparser.savefiles("e:\oletest\myscenarios\scenario1.slf") Set objparser = Nothing 'éteindre le serveur End Sub Lancement de l'exécutable du modèle et attendre la fin Dès que vous aurez modifié les paramètres dans votre application incorporante et sauvegardé le tout dans un fichier, lancez le modèle précompilé à partir de votre application et attendez que la tâche soit terminée. La fonction modèle VB funexeccmd ci-après est prise en grande partie de l'article TechNet de MS intitulé HOWTO: 32-Bit App Can Determine When a Shelled Process Ends, PSS ID Number: Q Guide du concepteur de Modgen v Sujets avancés en Modgen 157

166 Cet article vous présente des instructions détaillées sur la façon de lancer un exécutable de façon asynchrone, d'attendre qu'il soit terminé et de retourner ensuite à l'application contrôlante. Il faut se reporter à cet article pour connaître les déclarations type et API nécessaires à cette fonction. Il faut cependant prendre note de l'appel supplémentaire API à GetExitCodeProcess. Modgen renverra un code de sortie qu'on peut utiliser pour déterminer la façon dont la simulation a pris fin. Dans la version 6.0 de VB de Microsoft, on doit déclarer cet API de la façon suivante : Private Declare Function GetExitCodeProcess Lib "kernel32" _ (ByVal hprocess As Long, lpexitcode As Long) As Long Modgen renvoie les codes suivants : 0 l'application s'est terminée avec le Gestionnaire de tâches 1 exécution réussie 2 erreurs détectées 3 annulé, aucune sortie 4 interrompu, sorties partielles produites négatif - erreur d'exécution non détectée Le modèle de code : Private Function funexeccmd(cmdline$) As Long Dim proc As PROCESS_INFORMATION Dim start As STARTUPINFO Dim ret As Long Dim lngexitcode As Long ' Initialiser la structure STARTUPINFO : start.cb = Len(start) ' Lancer l'application tournant sous l'interprète de commande : ret = CreateProcessA(0&, CMDLINE$, 0&, 0&, 1&, _ NORMAL_PRIORITY_CLASS, 0&, 0&, start, proc) ' Attendre que l'application tournant sous l'interprète de commande se termine ret = WaitForSingleObject(proc.hProcess, INFINITE) If GetExitCodeProcess(proc.hProcess, lngexitcode) Then funexeccmd = 'erreur non interceptée 158 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

167 Else funexeccmd = -1 'erreur non interceptée End If ret = CloseHandle(proc.hProcess) End Function Par exemple, appelez la fonction ci-avant de VB de la façon suivante : frmmdi.hide 'dissimuler l'application incorporante lngexitcode = funexeccmd(strcmdline) frmmdi.show Select Case lngexitcode 'codé par Modgen Case 0 lblstatus.caption = "L'application s'est terminée avec le Gestionnaire de tâches." Case 1 lblstatus.caption = "La simulation s'est terminée correctement." Case 2 lblstatus.caption = "La simulation a produit une erreur." Case 3 lblstatus.caption = "La simulation a été annulée et aucun résultat partiel n'a été enregistré." Case 4 lblstatus.caption = "La simulation a été annulée et des résultats partiels ont été enregistrés." Case Else lblstatus.caption = "The simulation ended with a fatal run-time error." End Select Guide du concepteur de Modgen v Sujets avancés en Modgen 159

168 La chaîne strcmdline ci-avant renferme le nom de fichier de l'exécutable du modèle suivi de l'option sc sur la ligne de commande et d'un fichier de scénario sauvegardé. Mise en garde : tout nom de fichier valide qui renferme des blancs (cela inclut le nom de l'exécutable en première position) doit être précédé et suivi de guillemets doubles. Par exemple : strcmdline = """c:\statistics Canada\simpex\simpex.exe""" & _ strcmdline = strcmdline & " -sc """ & strfilesce & """" 160 Sujets avancés en Modgen Guide du concepteur de Modgen v10.1.0

169 Outils et techniques de débogage et d optimisation Introduction au débogage La lecture du présent exposé suppose que le concepteur du modèle possède une bonne connaissance des techniques de débogage en C++. L'un des plus puissants aspects de l'architecture Modgen est de permettre au concepteur de déboguer le code de son modèle à l'aide des fichiers.mpp. Même si l'on aura rarement à éditer un.cpp, prenez une seconde pour regarder sa structure. Vous constaterez qu'il se compose en premier lieu de directives numérotées pour le compilateur. En second lieu, sauf pour quelques exceptions après la première directive numérotée, Modgen maintient une correspondance entre chaque ligne de code du fichier.mpp et chaque ligne de code du fichier.cpp. Les trois étapes du débogage La première étape consiste à corriger les erreurs de syntaxe Modgen par le compilateur de Modgen après que vous exécutez Modgen.exe sur vos fichiers.mpp. Ainsi, toute erreur de syntaxe dans la définition d'un acteur sortira ici. Seules les erreurs de syntaxe dans les fichiers.mpp peuvent être décelées à cette étape. Modgen signale les erreurs de syntaxe dans les fichiers.dat au moment de l'exécution. La deuxième étape consiste à corriger les erreurs du compilateur et de l'éditeur de liens C++ pendant le processus de génération. Il s'agira habituellement d'erreurs de syntaxe ou de mots clés mal employés en C++, ou assez faciles à corriger. La troisième étape du débogage se produit après une compilation réussie en C++. À ce moment-là, les erreurs se produiront au moment de l'exécution du modèle et l'empêcheront de fonctionner, ou encore il pourra s'agir de graves erreurs de logique qui produiront des résultats incorrects. L'erreur la plus courante d'exécution dans Modgen est un renvoi à un pointeur nul. L'erreur de logique la plus courante dans Modgen sera une mauvaise spécification de tableau. Nous verrons dans le reste de cette section les erreurs de la troisième étape de débogage. Guide du concepteur de Modgen v Outils et techniques de débogage et d optimisation 161

170 Production d'une version de débogage On doit créer une version de débogage du fichier exécutable et régler la configuration active à l'option «Debug». Au moment de lancer le débogage, on peut insérer des points de rupture à des lignes de code appropriées (non dans les définitions de Modgen) dans les fichiers.mpp. Il est également possible d'instaurer des points de rupture dans les fichiers ACTORS.cpp et TABINIT.cpp (que produit Modgen), cependant il faut pour cela connaître en détail les rouages internes de Modgen et, de toute façon, leur utilité n'est pas très grande dans la plupart des cas. Lorsqu'il se produit une erreur pendant l'exécution, on doit examiner la pile d'appels. Parfois, l'erreur se produira à l'intérieur du fichier DLL de Modgen ou du fichier ACTORS.cpp ou TABINIT.cpp. Si c'est le cas, il y aura lieu d'examiner dans le fichier.mpp la fonction qui se trouve le plus haut dans la pile. Dans la plupart des cas, cela suffira à découvrir le problème. Pour afficher la valeur de la variable, tapez son nom dans la fenêtre «Watch». Seuls les noms de paramètre devant être précédés de mm::gprparam-> font l'objet d'un traitement spécial (p. ex., mm::gprparam->modelcohortonly). Dans ces exemples, «mm» est l espace de nommage de C++ utilisé par Modgen pour protéger les symboles ou éléments déclarés par le concepteur dans le code Le plus difficile pour un concepteur sera de corriger les erreurs de logique et de valider les tableaux. Si le passage est court, on pourra utiliser la base de données de suivi de concert avec le navigateur BioBrowser. Il est bon d'utiliser différents filtres pour observer de petits sous-ensembles de la population visée, de faire le suivi du plus grand nombre possible d'états et de toujours veiller à inclure dans le suivi la valeur d'amorçage du cas case_seed. Pour les passages plus longs, on peut ajouter l'expression min_value_in(case_seed) aux tableaux qui nous intéressent. Cette expression affichera la plus petite valeur d'amorçage du cas qui a débouché sur une entrée imprévue dans une case. On pourra ensuite utiliser cette valeur d'amorçage pour déboguer le cas problème. Il arrivera rarement que l'environnement de débogage donne des résultats différents de ceux de l'environnement de l'application elle-même. En pareil cas, pour simplifier le processus, il est bon de recompiler en désactivant toutes les optimisations du compilateur. Outils et techniques de débogage Vérification des bornes Paramètres : Les modèles Modgen compilés en mode de débogage vérifieront, lors de leur exécution, que chaque indice utilisé dans un paramètre de matrice n excède pas les bornes correctes de la dimension associée. Si l une des bornes d une matrice paramétrique n est pas respectée, le logiciel affichera une boîte de message décrivant le problème. La même information sera transcrite dans le ficheir de journalisation du scénario. Après l affichage de la boîte de message, 162 Outils et techniques de débogage et d optimisation Guide du concepteur de Modgen v10.1.0

171 une deuxième boîte de dialogue permettra à l utilisateur de quitter le modèle, d ignorer l erreur ou d appeler le débogueur. La fonction de vérification des bornes n est pas active dans les modèles compilés en mode de diffusion et n a aucun effet sur la performance dans ce mode. Dans le mode de débogage, on peut désactiver la fonction de vérification des bornes en définissant la constante manifeste MG_NCHKBND dans Visual Studio en sélectionnant «Preprocessor definitions» dans l onglet «C/C++» dans «Project Settings». Les concepteurs pourraient vouloir désactiver la fonction de vérification des bornes en mode de débogage s ils savent que leur modèle ne viole pas les bornes de matrice et qu il est essentiel d améliorer la performance en mode de débogage pour rechercher les causes d un problème particulier. Il est fortement conseillé aux concepteurs de modèles Modgen d utiliser le mode de débogage pour repérer les erreurs ayant trait aux bornes de matrice avant de diffuser les modèles aux utilisateurs ou à d autres concepteurs. Sinon, les nombreuses boîtes de messages d erreur produites à cause des violations des bornes matricielles pourraient compliquer l utilisation du modèle en mode de débogage sans parler du fait qu une importante erreur existe dans la logique. Membres de données des acteurs (matrices d états) : Modgen vérifie si les bornes des matrices de membres des données sur les acteurs sont respectées au moment de l exécution des modèles compilés en mode de débogage. Cette fonction est exécutée de la même façon que dans le cas des paramètres matriciels. La vérification des bornes diminue d environ 30 % la vitesse de simulation des modèles compilés en mode de débogage. États de type classification : Lors de l exécution d un modèle compilé en mode de débogage, Modgen produira une boîte de message si l utilisateur essaie d attribuer une valeur invalide à un état de type classification. Le message indique le nom de l état et la valeur à attribuer. En mode diffusion, ces valeurs sont forcées silencieusement à correspondre aux première et dernière valeurs de la classification. Vérification de l intégrité de la mémoire En mode de débogage, Modgen vérifie automatiquement l intégrité de certaines structures internes de la mémoire et affiche une boîte de message si le code de l utilisateur a compromis ces structures. Cette vérification ne garantit pas que le code de l utilisateur ne contient aucune erreur, mais fournit un moyen éventuel de déterminer si le code de l utilisateur est la cause de comportements anormaux, comme des arrêts imprévus, etc. Notez que le code de l utilisateur reste néanmoins fort capable de compromettre la stabilité de l exécutable du modèle. Guide du concepteur de Modgen v Outils et techniques de débogage et d optimisation 163

172 Check Sum Modgen peut générer un nombre «unique» pour chaque cas simulé, à partir des événements qui se produisent lors de la simulation du cas et du temps au moment où chaque événement se produit. Cette fonctionnalité peut être activé en mode de débogage comme en mode de diffusion en définissant la constante manifeste MG_CHKSUM dans Visual Studio en utilisant «Preprocessor definitions» dans l'onglet «C/C++» du dialogue «Project Settings». La valeur d'amorçage du cas ainsi que la valeur du «check sum» pour chaque cas seront alors écrites dans le fichier de débogage (ex. Base(debug).txt). Par exemple, cette fonctionnalité peut être utilisée pour identifier un cas qui diffère entre deux simulations qui devraient être identiques. Trace des événements Les modèles Modgen peuvent garder la trace de chaque événement qui se produit pendant un cas ou pendant une portion de cas. Cette fonctionnalité peut être activé en mode de débogage ou mode de diffusion en définissant la constante manifeste MG_TRCEVNT dans Visual Studio en utilisant «Preprocessor definitions» dans l onglet «C/C++» du dialogue «Project Settings». De plus, le concepteur de modèle peut également spécifier dans le code quand commencer à garder une trace des événements et quand arrêter. Pour ce faire, Modgen utilise les deux fonctions: StartEventTrace() et StopEventTrace(). void StartEventTrace( ); void StopEventTrace( ); Le fait de garder une trace de chaque événement rend la simulation extrêmement lente, alors il est sage de limiter autant que possible l utilisation de cette fonctionnalité. Le modèle garde une trace des événements en insérant une entrée pour chacun d eux dans le fichier de débogage (ex. Base(debug).txt). Cette entrée contient la valeur d amorçage du cas, l identificateur de l acteur, le nom de l acteur (ex. Person), le nom de l événement ainsi que le temps lorsque l événement s est produit. Dans le cas d événements autodatés (scheduled), le mot «schedule» suivi du numéro identificateur de l événement remplacera le nom de l événement. Cette fonctionnalité peut être utilisée, par exemple, après qu un cas a été identifié avec la méthode «check sum», pour identifier le premier événement qui diffère. Fonction SkipCases Cette fonction vous permet de «sauter» la simulation d un nombre de cas donné en argument. SkipCases démarre les cas et les arrête de sorte que la prochaine valeur d amorçage soit la même que si les cas avaient été simulés. 164 Outils et techniques de débogage et d optimisation Guide du concepteur de Modgen v10.1.0

173 Supposons que vous aviez la série de trois cas ayant les valeurs d amorçage suivantes : Cette fonction facilite le débogage parce qu elle rend possible le fait de ne simuler, par exemple, que la deuxième moitié d une simulation, ou les derniers dix cas. SkipCases doit être appelée avant que des cas soient simulés dans ce fil d exécution. Pour l utiliser, créez un paramètre contenant le nombre de cas à «sauter» et appelez cette fonction avant d appeler CaseSimulation dans chaque fil d exécution. Si un cas a été simulé dans le fil d exécution avant l appel à SkipCases, un message d erreur apparaîtra et la simulation continuera sans que des cas soient sautés dans ce fil. Voici un exemple dans Simpex : void Simulation() { long lcase; SkipCases(CasesToSkip); // boucle qui simule les cas for ( lcase = 0; lcase < CASES() &&!gbinterrupted &&!gbcancelled &&!gberrors; lcase++ ) { } // simule le prochain cas StartCase(); CaseSimulation(); SignalCase(); } où CasesToSkip est un paramètre créé pour contenir le nombre de cas que je souhaite «sauter». Notez que le nombre de cas indiqué dans le scénario n inclus pas le nombre de cas «sautés». Modgen «sautera» le nombre de cas donné en argument à la fonction SkipCases puis simulera le nombre de cas demandé dans le scénario. Par exemple, si je demande 10 cas dans le scénario et que je mets CasesToSkip = 1000, le modèle «sautera» 1000 cas mais simulera quand même 10 cas, tel que demandé. Autre exemple : pour simuler la deuxième moitié d une simulation de cas, il faut demander une simulation de cas et préciser de sauter cas. Guide du concepteur de Modgen v Outils et techniques de débogage et d optimisation 165

174 WriteDebugLogEntry La fonction «WriteDebugLogEntry» écrira dans le fichier scenario_name(debug).txt. Cette fonction peut être utilisée en mode de diffusion et en mode de déboguage. Cependant, cette fonction ne peut pas être utilisée dans les simulations distribuées. La façon la plus simple de l utiliser est de lui donner une chaîne de caractères en argument. Voici un exemple : CString szdebugexample = ""; szdebugexample = "Maintenant dans BirthdayEvent"; WriteDebugLogEntry(szDebugExample); Veuillez noter que l utilisation de cette fonction, comme la trace des événements, rendra ce fichier gigantesque. Cette fonction devrait n être utilisée que lorsque rien d autre ne fonctionne. Comment exécuter une réitération particulière dans un modèle temporel Un cas particulier dans un modèle de cas peut être précisé avec la valeur d amorçage. Les modèles temporels n ont pas de fonctionnalité équivalente pour simuler une réitération particulière lorsque des réitérations multiples avaient été demandées. Simuler une réitération particulière peut parfois être utile pour des raisons de débogage. Pour ce faire, insérer une ligne semblable à la ligne suivante au tout début de la fonction «Simulation()» : // simulate only replicate #4 if ( 4!= GetReplicate() ) return; Gestion des erreurs d exécution Certaines erreurs d exécution peuvent se produire lors de l exécution du code d un modèle pendant la simulation telles que la division par zéro, le manque de mémoire, etc. Dans les versions de distribution des modèles, une erreur d exécution produira un message contenant de l information utile qui sera affichée dans la boîte «Erreurs et avertissements» au bas de la fenêtre de progrès du modèle. Le message sera également écrit dans le fichier de journalisation du scénario. Le modèle ne produira aucun tableau mais produira un 166 Outils et techniques de débogage et d optimisation Guide du concepteur de Modgen v10.1.0

175 fichier de suivi si le suivi a été activé. Si le modèle tournait en mode interactif, la simulation se terminera immédiatement mais l interface continuera à fonctionner. Si le modèle tournait en mode d exécution par lots, le modèle fermera avec un code de retour de «2». Si la machine participait à un pool de Executor, une erreur d exécution dans un modèle Modgen permettra à la machine d exécuter d autres tâches après. Lorsqu une erreur d exécution se produit dans une version de distribution d un modèle, l information présentée dépendra de la nature de l erreur, du type de modèle (modèles de cas, modèles temporels, modèles de cellules), et de la phase de l exécution (PreSimulation, Simulation, PostSimulation, UserTables). L exemple suivant est extrait d un fichier de journalisation d un scénario pour un modèle de cas dans lequel l erreur s est produite pendant la phase de simulation : Error: Type: invalid argument to sqrt() Phase: Simulation Subsample: 1 Event: Person.AgeOneYearEvent(implement) case_seed = time = actor_id = 33 Comme on peut le voir dans l exemple précédent, le nom de l événement ainsi que la fonction («time» ou «implement» dans lesquels l erreur s est produite sont indiqués. À noter qu une erreur d exécution qui se produit pendant l implémentation d un événement pourrait n être qu indirectement reliée au code de la fonction «Implement» de l événement. Par exemple, si «a» est un état simple et «b» un état dérivé défini comme «b = exp(a);», une fonction d implémentation d événement qui ferait «a = 1000;» produirait une erreur d exécution associée à l événement même si l appel à la fonction «exp» qui a généré l erreur n est pas situé dans le code de la fonction d implémentation de l événement. L information sur l erreur peut contenir le «actor_id». C est utile pour identifier quel acteur était responsable de l erreur. Pour que les valeurs de «actor_id» soient reproductibles, la valeur d amorçage du scénario doit être identique et le nombre de fils d exécution dans le scénario devrait être mis à «1». Pratiquement toutes les erreurs d exécution (incluant les erreurs de manque de mémoire et les erreurs de lecture ou d écriture à un endroit incorrect de la mémoire) sont captées et affichées dans la version de distribution des modèles. Il y a des mesures précises pour identifier les erreurs qui proviennent d arguments invalides aux fonctions mathématiques fréquemment utilisées «exp()», «log()», «pow()» et «sqrt()». La plupart des erreurs seront affichées avec de l information compréhensible sous «Type :» mais dans certains cas rares, il se peut que la documentation du système Guide du concepteur de Modgen v Outils et techniques de débogage et d optimisation 167

176 soit nécessaire pour comprendre l erreur. Par exemple, l erreur «EXCEPTION_STACK_OVERFLOW» peut provenir du code d un modèle qui essaie de créer un nombre excessivement grand de matrices dans une variable temporaire d une fonction. L erreur «EXCEPTION_IN_PAGE_ERROR» peut survenir d un modèle tourné à travers un réseau qui n utilise pas l option «/SWAPRUN:NET». Lorsqu une erreur d exécution survient dans la version de débogage d un modèle, l erreur n est pas captée par Modgen. Une boîte de dialogue est présentée qui permet d entrer dans le Debugger de Visual Studio pour identifier le code du modèle qui cause le problème. Selon l endroit et la nature du problème, il peut être nécessaire d utiliser d abord la fenêtre «call stack» de Visual Studio et de sélectionner la fonction du modèle qui exécutait au moment où l erreur s est produite. Application Cleaner L installation de Modgen inclut l application Cleaner.exe, petite application qui supprime tous les fichiers provisoires Modgen du dossier provisoire (MDGNxxx.xxx), sans supprimer les fichiers qui n ont pas été créés par Modgen. Durant l installation de Modgen, un raccourci sera ajouté dans votre dossier de démarrage. Par conséquent, lorsque vous redémarrerez votre ordinateur, les fichiers Modgen seront supprimés de votre dossier provisoire. Cette opération se fera en mode silencieux. L application a été créée pour éviter que les simulations s arrêtent de façon imprévue à cause d un manque d espace disque. À moins que votre ordinateur soit en train d exécuter une simulation, vous pouvez utiliser l application n importe quand pour supprimer des fichiers Modgen de votre dossier provisoire, par exemple après des sessions de débogage. Cependant, vous NE devez PAS utiliser l application lorsqu une simulation est en cours, sinon celle-ci s arrêtera et vous perdrez les données. Techniques d optimisation Exécution fiable des modèles à travers le réseau Les modèles Modgen prennent souvent beaucoup de temps à tourner. Si un modèle tourne à travers un réseau (ex. si l exécutable se trouve sur un serveur mais est exécuté par un poste de travail), des connections désuètes et d autres curiosités de réseautique peuvent créer des erreurs d exécutions mystérieuses. La solution à ce problème implique une modification des propriétés de chaque projet de modèle Modgen dans Visual Studio. Ouvrez le fichier de solution (.sln) du projet dans Visual Studio et choisissez «Project / Properties». Sous «Configuration Properties» dans le panneau à gauche, cliquez «Linker» et donc choisissez «System». Puis changez la 168 Outils et techniques de débogage et d optimisation Guide du concepteur de Modgen v10.1.0

177 propriété «Swap Run from Network» de «No» à «Yes», et recompilez le modèle. Il est également possible d activer cette option dans un exécutable existant sans le recompiler. Cela peut être utile pour tourner d anciens modèles (compilés avec une ancienne version de Modgen ou de Visual Studio, par exemple) de façon fiable à travers un réseau. Pour activer cette option dans un exécutable existant sans le recompiler, ouvrez la fenêtre de commande et tournez l utilitaire EDITBIN (fourni par Visual Studio) en activant l option SWAPRUN comme dans l exemple suivant : EDITBIN /SWAPRUN:NET simpex.exe Ces changements ont été faits dans le projet Visual Studio du modèle Simpex qui est fourni avec Modgen. Augmenter la mémoire disponible pour les modèles Modgen avec le système d exploitation Windows x64 La mémoire disponible pour un modèle Modgen peut être doublée si le modèle est exécuté sur une machine ayant un système d exploitation à 64-bits tel que Windows XP x64 Edition. Cela peut être particulièrement intéressant pour les modèles temporels pour lesquels la mémoire est une limite importante. Pour utiliser cette fonctionnalité, ouvrez le fichier de solution (.sln) de Visual Studio et choisissez «Project / Properties». Dans le panneau à gauche, cliquez «Linker» sous «Configuration Properties» et choisissez «System». Changez la propriété «Enable Large Addresses» à «Support Addresses Larger Than 2 Gigabytes (/LARGEADDRESSAWARE)». Recompilez le modèle. Il est également possible d activer cette option dans un exécutable existant sans recompiler le modèle. Utilisez l utilitaire «EDITBIN» (fourni avec Visual Studio) comme dans l exemple suivant : EDITBIN /LARGEADDRESSAWARE simpex.exe La commande «options» Le mot clé options est suivi d une ou plusieurs options séparées par des espaces. Chaque option a la forme d un mot clé suivi par le symbole =, suivi de la valeur de l option. Le code source peut contenir plusieurs commandes options, qui ont un effet cumulatif. Si la même option est donnée plusieurs fois dans le code source du modèle, la dernière rencontrée par Modgen prédomine. Quelques capacités de Modgen qui auparavant nécessitaient au concepteur de changer des options du compilateur C++ pourraient maintenant être précisées avec la commande options. Exemple : options bounds_errors=off; Guide du concepteur de Modgen v Outils et techniques de débogage et d optimisation 169

178 Le tableau suivant donne les options disponibles dans la version actuelle de Modgen et le constant manifeste C++ équivalent s il y en a une. Option Valeur Déscription L option de de compilateu défaut r équivalente bounds_errors = on on Fait fonctionner des erreurs en MG_NCHKL off temps réel quand le modèle donne MT (pas une mauvaise valeur à une variable documenté) de type range ou classification (version Debug seulement) index_errors = on on Fait fonctionner des erreurs en MG_NCHKB off temps réel quand le modèle utilise ND une mauvaise valeur comme indice d une matrice (version Debug seulement) case_checksum = on off Fait fonctionner la production d un MG_CHKSU off somme de contrôle pour chaque M cas (versions Debug et Release) event_trace = on off off Fait fonctionner la capacité de suivi d évènements (version MG_TRCEV NT Debug, requiert aussi l utilisation des fonctions assistants). fp_consistency = on off Fait fonctionner la capacité du rien off compilateur C++ de produire du code de nombres flottants plus cohérent mais moins efficace. packing_level = Fait fonctionner la capacité d optimiser la mémoire des états d acteurs. rien 170 Outils et techniques de débogage et d optimisation Guide du concepteur de Modgen v10.1.0

179 permit_all_cus = on off Fait fonctionner la capacité des rien off états mis à jour continuellement d être utilisés dans les fonctions temps d événements, ainsi que comme filtre ou dimension de classification des tableaux; «off» indique que cette utilisation soit interdite Option «bounds_error» Quand un modèle donne une valeur à un état d acteur de type classification ou étendue, Modgen s assure toujours que la valeur tombe dans les bornes en tronquant à la valeur minimum ou maximum. Le comportement de produire délibérément des erreurs en temps réel quand le modèle donne une valeur invalide à un état d acteur de type classification ou étendue est mis en marche ou désamorcé avec l option bounds_errors. Ça permet au développeur d utiliser des range petits dans des modèles basés sur le temps pour améliorer l efficacité de mémoire (en conjonction avec l option packing_level). Option «fp_consistency» Dans des versions Release des modèles, le compilateur C++ optimise normalement la vitesse des opérations de nombre flottants. Des petits changements dans le code d un modèle qui n en affectent pas la logique comme ceux produits par l option packing_level peuvent produire des différences dans des résultats quand le compilateur optimise du code de nombres flottants. Si on met fp_consistency à on, ça réduit ou élimine ce phénomène, mais le modèle que en résulte sera plus lent. Cette option n a aucun effet pour des versions Debug du modèle configuré normalement. L option fp_consistency peut être utile quand on test pour des différences parmi des versions différentes des modèles. Option «packing_level» L option packing_level contrôle comment Modgen définit et ordonne des états d acteur pour réduire l utilisation de mémoire. L option peut être utile dans des modèles time_based ayant beaucoup d acteurs. Des valeurs plus hautes de packing_level réduisent l utilisation de mémoire, mais au prix d augmenter le temps d exécution. La valeur de défaut de packing_level est 0, ce qui implique que Modgen ne fait rien de spéciale à part d ordonner efficacement les membres des classes et structures C++. Si packing_level est 1, Modgen utilise le plus petit type intègre simple de C++ pour stocker Guide du concepteur de Modgen v Outils et techniques de débogage et d optimisation 171

180 des variables de type classification, partition, range et logical. Si packing_level est 2, Modgen stocke des variables des variables de type classification, partition, range et logical dans le minimum de bits possible. Le tableau suivant résume les valeurs disponibles de packing_level : packing_ level Description 0 Utilise le type C++ type int pour stocker des variables de type range, classification, partition, et logical. 1 Utilise le plus petit type intègre simple de C++ pour stocker des variables de type classification, partition, range, et logical. 2 Utilise le minimum de bits possible pour stocker des variables de type classification, partition, range, et logical. Pour des versions Release des modèles, des différences dans le code optimisé produit par le compilateur C++ peuvent produire des différences dans les résultats en fonction de la valeur de packing_level. Ça n affecte pas les versions Debug des modèles. Dans des situations où la cohérence est plus importante que l efficacité, le concepteur de modèle peut utiliser l option fp_consistency pour désamorcer l optimisation du code de nombre flottants dans la version Release d un modèle. Si packing_level est 1 ou 2, ça causera une erreur de compilation C++ dans le module fréquemment utilisé Clock.mpp. Pour éliminer l erreur, il faut changer les lignes logical logical logical logical bdayboundary = {FALSE}; bweekboundary = {FALSE}; bmonthboundary = {FALSE}; byearboundary = {FALSE}; à BOOL bdayboundary = {FALSE}; BOOL bweekboundary = {FALSE}; 172 Outils et techniques de débogage et d optimisation Guide du concepteur de Modgen v10.1.0

181 BOOL bmonthboundary = {FALSE}; BOOL byearboundary = {FALSE}; Dans les deux fonctions ClockEvent et FinishClock. Le rapport d utilisation de mémoire n inclut pas l effet de packing_level. Ce rapport sera mis à jour dans une version ultérieur de Modgen. Option «permit_all_cus» À moins que cette option soit activée par l utilisateur, il est interdit d utiliser les états mis à jour continuellement dans les fonctions temps d événements, ainsi que comme filtre ou dimension de classification des tableaux. Dans de telles situations, Modgen retournera une erreur et indiquera l utilisation illégale d un état mis à jour continuellement. Le modèle ne pourra pas être compilé. Si Modgen retourne une erreur indiquant une utilisation illégale d un état mis à jour continuellement et que vous voulez avoir plus d information, vous pouvez utiliser le fichier d aide. Pour pouvoir produire le fichier d aide, le modèle doit d abord être compilé. Au besoin, vous pouvez activer temporairement l option «permit_all_cus», compiler le modèle et produire le fichier d aide pour ensuite désactiver de nouveau cette option. Le fichier d aide contient une liste de tous les états mis à jour continuellement et leurs utilisations. Pour chaque état mis à jour continuellement, les états qui en sont derivés, qui sont également mis à jour continuellement, sont également indiqués, ce qui permet de comprendre facilement pourquoi un état est mis à jour continuellement. Les états mis à jour continuellement sont : age time duration( ) weighted_duration( ) active_spell_duration( ) active_spell_weighted_duration( ) tout état derivé d un des précédents Guide du concepteur de Modgen v Outils et techniques de débogage et d optimisation 173

182 Les états ayant le même nom de membre (sans le nom de l acteur) qu un état mis à jour continuellement d un autre acteur sont également considérés comme étant mis à jour continuellement et ne peuvent pas être utilisé dans les fonctions temps d événements. Par contre, ces états peuvent être utilisés comme filters de tableaux ou comme dimensions de classification des tableaux. Comment améliorer l efficacité de l utilisation de mémoire dans les modèles temporels Des modèles «time_based» avec beaucoup d acteurs demandent beaucoup de mémoire. Le nombre maximum d acteurs qu on peut simuler est limité par la mémoire disponbile et l efficacité d utilisation de cette mémoire-là. Cette section comprend des recommandations pour améliorer l efficacité de mémoire dans des modèles Modgen «time_based». Ces recommandations sont soumises à des particularités de chaque modèle. Déclarer toutes les états d acteur nombre flottant comme real au lieu de double ou float, et préciser real_type float; Déclarer toutes les états d acteur intègre comme range au lieu de int, et préciser options bounds_errors=off; et options packing_level=2; Préciser ou options packing_level=1; ou options packing_level=2; Mettre le nombre de fils dans «Scénario / Mise en place» à 1, si le modèle peut être tourné sur une machine ayant plus d un processeur ou avec un processeur hyper thread. Préciser time_type float; Si le modèle le permet, préciser counter_type ushort; Si le modèle le permet, préciser integer_type short; 174 Outils et techniques de débogage et d optimisation Guide du concepteur de Modgen v10.1.0

183 Si le nombre de cases dans n importe quel tableau est moins que (le nombre de réitérations demandé dans le scénario peut influencer ce nombre), préciser index_type ushort; Examiner le rapport sur l utilisation de mémoire pour mieux comprendre quelles parties du modèle utilisent le plus de mémoire. L utilisation des modules distincts rend le rapport plus utile. Mettre en commentaires des tableaux inutiles ou rarement utilisés dans le code source du modèle. Mettre des tableaux rarement utilisés et les états d acteurs connexes dans des modules à part pour les exclure facilement de la version de production du modèle. Songer à des designs logiquement équivalents qui réduisent le nombre d évènements déclarés dans le modèle. Songer à des designs logiquement équivalents qui réduisent le nombre d états d acteurs. Guide du concepteur de Modgen v Outils et techniques de débogage et d optimisation 175

184

185 Matériel de référence Aperçu du résumé des commandes Cette section énumère les définitions, mots clés, expressions et fonctions spéciales selon la nature de leur utilisation. Son but est de présenter un sommaire syntaxique du langage Modgen. La modification des valeurs des paramètres et leur ordre d'affichage sont les seules fonctions de Modgen qu'on peut exécuter à l'égard des paramètres au moment de l'exécution du programme. Toute autre modification exige une recompilation du modèle. Par exemple, une modification du rang (nombre de dimensions), de la forme et du type de paramètre nécessitera une nouvelle compilation. De plus, tout changement de la déclaration de suivi dans le fichier de suivi du BioBrowser (p. ex., modifier le filtre ou ajouter un autre état de suivi à l'égard d'un acteur) exigera de l'utilisateur qu'il procède à une nouvelle compilation. Pour ce qui est des sorties, on ne peut pas modifier les tableaux sans recompiler l'exécutable. Cependant, les paramètres de contrôle de la simulation vous permettent d'établir les tableaux et les paramètres à produire. Définitions et mots clés actor actor_name { elements}; Définition d'un acteur.mpp aggregation aggregated_classification, detailed_classification { Définition d'une agrégation.mpp classification classification_name { elements }; Définition d'un type de classification.mpp cumrate parameter_name event time_function,implement_function<,priority_cod e> Définition du paramètre de modèle du type cumrate Définition d'un événement dans la définition d'un acteur.mpp,.dat.mpp extend_parameter parameter1<,parameter2>; Prolongement des données du paramètre.mpp Guide du concepteur de Modgen v Matériel de référence 177

186 FALSE hook from_function_name, to_function_name; languages entreposées Valeur possible de la variable logique du modèle Définition d'un crochet de fonction dans une fonction d implementation d un événement ou une fonction du membre Définition des langues utilisées dans le modèle.mpp,.dat.mpp.mpp link actor_name1 actor_name2; Établissement d'un lien entre acteurs.mpp logical variable_name Définition d'un état ou d'un paramètre logique.mpp,.dat model_type case_based/time_based/cell_based; Définition du type de modèle.mpp model_generated parameter_name Définition d'un paramètre créé par le modèle.mpp NULL Mot clé spécial pour un pointeur nul.mpp parameter_group group_name {name,,name}; parameters { model_parameters }; Définition d'un groupe de paramètres Définition d'un ensemble de paramètres de modèle.mpp.mpp,.dat partition partition_name { elements }; Définition d'une partition de modèle.mpp piece_linear parameter_name range range_name { elements }; table <sparse> actor_name <table_name> <[filter]> { elements }; Définition d'un paramètre de modèle du type piece_linear Définition d'une fourchette dans le modèle Définition d'un tableau.mpp,.dat.mpp,.dat.mpp table_group group_name {name,,name}; Définition d'un groupe de tableaux.mpp TIME variable_name Définition d un état du type TIME.mpp TIME_INFINITE Variable spéciale du temps d'attente avant.mpp 178 Matériel de référence Guide du concepteur de Modgen v10.1.0

187 time_type value; TIME_UNDEF track actor_name [intial_filter<,final_filter>] { elements }; TRUE UNDEF_VALUE user_table <sparse> table_name {elements}; version value; l'événement suivant Définit le type de modèle de microsimulation Variable spéciale du temps d'attente avant l'événement suivant Définition des états à suivre à l'égard d'un acteur donné Valeur possible de la variable logique du modèle Définition de valeurs nulles dans les tableaux d'utilisateur Définition d'un tableau d'utilisateur Affectation d'un numéro de version au modèle.mpp.mpp.mpp.mpp,.dat.mpp.mpp Note 1 : Si des étiquettes descriptives sont requises, vous devez utiliser plus d'une ligne. Note 2 : < > signifie des arguments facultatifs, indique une déclaration incomplète. Expressions d état dérivés utilisées dans les définitions de tableaux et d acteurs changes( variable ) active_spell_delta( variable, state, analysis variable ) active_spell_duration( variable, state) active_spell_weighted_duration( variable, state, weighting variable ) duration( variable,state ) duration_trigger( state,value,elapsed_time ) duration_counter( state, value,size of time interval, maximum value ) Nombre de changements d un état Changement d'une variable d'analyse pour l'état actuel d'un état Durée de l'état actuel d'un état Sommation d'un état sur la période actuelle Durée d'un certain état d'un état 1 pour une durée précise d'un certain état d'un état Le nombre d intervalles d une grandeur précisée qui se sont écoulés depus qu un état particulier a atteint une valeur Guide du concepteur de Modgen v Matériel de référence 179

188 particulière, jusqu à la valeur maximum (si fournie) est atteinte. entrances( variable, state ) exits( variable, state ) completed_spell_delta( variable, state, analysis variable ) completed_spell_duration( variable, state ) completed_spell_weighted_duration( variable, state, weighting variable ) split( state variable, parition_name ) transitions( variable, from state, to state ) undergone_change( variable ) undergone_entrance( variable, state ) value_at_changes( variable, recorded variable ) value_at_entrances( variable, state, recorded variable ) value_at_exits( variable, state, recorded variable ) value_at_first_change( variable, recorded variable ) value_at_first_entrance( variable, state, recorded variable ) value_at_latest_change( variable, recorded variable ) value_at_latest_entrance( variable, state, Nombre de fois qu'un état est entré dans un certain état Nombre de fois qu'un état est sorti d'un certain état Changement de la variable d'analyse pendant la dernière période terminée où un acteur était dans un certain état Durée de la dernière période terminée où un acteur était dans un certain état Sommation d' sur la dernière période terminée où un acteur était dans un certain état Division d'une variable d'analyse en catégories (dimension de tableau) Nombre de fois qu'un état est passé d'un certain état à un autre état Valeur de la variable d'analyse au premier changement d'un certain état d'un état Valeur de la variable d'analyse à la première entrée dans un certain état d'un état Somme des valeurs d'une variable d'analyse aux changements d'un certain état Somme des valeurs d'une variable d'analyse à l'entrée dans un certain état Somme des valeurs d'une variable d'analyse à la sortie d'un certain état Valeur d'une variable d'analyse au premier changement d'un certain état Valeur d'une variable d'analyse à la première entrée dans un certain état Valeur d'une variable d'analyse au dernier changement d'un certain état Valeur d'une variable d'analyse à la dernière entrée dans un 180 Matériel de référence Guide du concepteur de Modgen v10.1.0

189 recorded variable ) value_at_transitions( variable, from state, to state, recorded variable ) weighted_cumulation( state1,state2 ) weighted_duration( <variable, state,> weighting variable ) certain état Somme des valeurs d'une variable d'analyse au passage d'un certain état à un certain autre état Lorsque l'état 1 change, multiplication par l'état 2 avant la sommation Sommation d'un état sur la durée d'un certain état Expressions utilisées dans les définitions de tableaux seulement delta( state ) delta2( state ) event( state ) interval( state ) max_delta( state ) max_value_in( state ) max_value_out( state ) min_delta( state ) min_value_in( state ) min_value_out( state ) nz_delta( state ) nz_value_in( state ) nz_value_out( state ) sqrt( state ) unit value_in( state ) Changement de valeur d'une variable d'analyse Changement quadratique de valeur d'une variable d'analyse Indication d'un changement simultané des variables d'analyse et de classification selon une nouvelle catégorie Indication d'un changement simultané des variables d'analyse et de classification selon une ancienne catégorie Changement maximal Valeur maximale à la première entrée dans une case de tableau Valeur maximale à la sortie d'une case de tableau Changement minimal Valeur minimale à la première entrée dans une case de tableau Valeur minimale à la sortie d'une case de tableau 1 si la valeur d'une variable d'analyse change 1 si la valeur de la variable d'analyse est non nulle à l'entrée d'une case du tableau 1 si la valeur de la variable d'analyse est non nulle à la sortie d'une case du tableau Racine carrée d'une variable d'analyse Nombre d'acteurs qui sont entrés dans chaque case de tableau Valeur de la variable d'analyse à la première entrée dans une case de Guide du concepteur de Modgen v Matériel de référence 181

190 tableau value_in2( state ) value_out( state ) value_out2( state ) Valeur quadratique de la variable d'analyse à la première entrée dans une case de tableau Valeur de la variable d'analyse à la sortie d'une case de tableau Valeur quadratique de la variable d'analyse à la sortie d'une case de tableau Commandes et fonctions utilisées avec les liens Add( actor_pointer ) count( link_name ) IMPLEMENT_HOOK FinishAll( ) *GetNext( int ninitpos, int *pnpos ) max_over( link_name, state_name ) min_over( link_name, state_name ) Remove( int nposition ) RemoveAll( ) sum_over( link_name, state_name ) Ajoute au lien un acteur du bon type Dénombre les acteurs reliés d'un certain type Localise un crochet de fonction Appelle la fonction de suspension générale Indique la position de l'acteur suivant dans un lien multiple Établit le maximum d'une certain état sur tous les acteurs liés Établit le minimum d'une certain état sur tous les acteurs liés Retire du lien un acteur à la position spécifiée Retire tous les acteurs du lien Fait la sommation de l'état demandé sur tous les acteurs liés Fonctions C++ fournies par Modgen Les fonctions C++ fournies par Modgen sont résumées dans la section intitulée «Fonctions et macro-instructions d exécution». On peut les utiliser n'importe où dans le code Modgen. Contenu de la base de données de la documentation de Modgen Le concepteur d'un modèle Modgen a la possibilité de documenter, grâce à une courte étiquette descriptive ou par un 182 Matériel de référence Guide du concepteur de Modgen v10.1.0

191 texte plus long, tous les éléments (acteurs, états, paramètres, événements, tableaux, etc.) d'un modèle donné. Si le concepteur fournit ce texte descriptif en plusieurs langues, le modèle pourra alors produire des sorties dans la langue choisie par l'utilisateur au moment de l'exécution. La base de données de documentation saisit tous les renseignements pertinents dans une base de données Access de MS, qui comprendra les tableaux suivants : Tableau : VersionInfo Description : Version du fichier. Zones : Version Tableau : LanguageDic Description : Dictionnaire des langues supportées. La langue choisie au moment de l'exécution est mentionnée dans la zone Selected. On y trouve aussi la traduction de quelques mots clés Modgen importants (dans les zones All, Min, Max, Contents, Parameters). Zones : LanguageID (numeric), LanguageCode (p. ex., «FR» pour français), LanguageName, All, Min, Max, Contents, Parameters Tableau : AutoParserErrorDic Description : Descriptions des erreurs renvoyées par le serveur OLE Autoparser Modgen. Zones : ErrorID, ErrorDescription, LanguageID Tableau : TypeDic Description : Dictionnaire de tous les types de variable utilisés dans un modèle. Comprend les types simples, les classifications, les fourchettes et les partitions. On peut obtenir plus de renseignements sur chaque type en consultant le dictionnaire particulier (indiqué par la zone DicID) à la zone TypeID. Zones : TypeID, DicID ( 0 - SimpleTypeDic, 1 - LogicalDic, 2 - ClassificationDic, 3 - RangeDic, 4 - PartitionDic, 5 - LinkTypeDic) Tableau : SimpleTypeDic Description : Dictionnaire des types simples de données : int, long, float, double, TIME, cumrate, piece_linear. Zones : TypeID (voir TypeDic), Name Tableau : LogicalDic Description : Contient les valeurs et les descriptions associées au type logical. Guide du concepteur de Modgen v Matériel de référence 183

192 Zones : TypeID, Name, Value, ValueName, ValueDescription, LanguageID Tableau : ClassificationDic Description : Dictionnaire de toutes les classifications. Zones : TypeID, Name, Description, Note, SourceFileID, NumberOfValues, LanguageID, ContextID Tableau : AggregationDic Description : Dictionnaire de toutes les agrégations. Zones : Name, AggregatedClassificationID, DetailedClassificationID Tableaux d'agrégation (nommés en fonction de l'aggregationdic) Description : Mappage détaillé d'une agrégation particulière. Zones : DetailedValue, AggregatedValue Tableau : RangeDic Description : Dictionnaire de toutes les fourchettes. Zones : TypeID, Name, Description, Note, SourceFileID, Min, Max, LanguageID, ContextID Tableau : PartitionDic Description : Dictionnaire de toutes les partitions. Zones :TypeID, Name, Description, Note, SourceFileID, NumberOfValues, LanguageID, ContextID Tableau : LinkTypeDic Description : Dictionnaire de tous les types de lien. Zones :TypeID, Name, LinkedActorID Tableau : ClassificationValueDic Description : Dictionnaire de tous les membres de l'ensemble des classifications. Zones : TypeID, EnumValue, Name, Description, Note, LanguageID, ContextID Tableau : PartitionValueDic Description : Dictionnaire de tous les points de rupture de l'ensemble des partitions. Chaque point de rupture est stocké 184 Matériel de référence Guide du concepteur de Modgen v10.1.0

193 sous forme d'un nombre et d'une chaîne. Zones : TypeID, Position, Value, StringValue Tableau : ParameterDic Description : Dictionnaire de tous les paramètres. Zones : ParameterID, Name, Description, Note, SourceFileID, TypeID, Rank, NumberOfDatapoints, NumberOfCumulatedDimensions, ModelGenerated (Yes/ No), Extendible (Yes/ No), RelatedParameterID, LanguageID, ContextID Tableau : ParameterDimensionDic Description : Dictionnaire de toutes les dimensions de l'ensemble des paramètres. Zones : ParameterID, Position, TypeID, DisplayPosition Tableau : ParameterDependencyDic Description : Dictionnaire des dépendances de paramètre des extensions de paramètre. Zones : ParameterID, DependentParameterID Tableau : ParameterGroupDic Description : Dictionnaire de tous les groupes de paramètres. Zones : ParameterGroupID, Name, Description, Note, LanguageID, ContextID Tableau : ParameterGroupMemberDic Description : Dictionnaire de tous les membres de l'ensemble des groupes de paramètres. Zones : ParameterGroupID, Position, ParameterID, MemberGroupID Tableau : ParameterSheetDic Description : Noms de toutes les feuilles d'excel de MS pour l'ensemble des paramètres de sortie. Les noms sont créés uniquement lorsqu'on demande une sortie Excel. Zones : ParameterID, SheetID, SheetName Tableau : ActorDic Description : Dictionnaire de tous les acteurs. Zones : ActorID, Name, Description, Note, LanguageID, ContextID Guide du concepteur de Modgen v Matériel de référence 185

194 Tableau : ActorStateDic Description : Dictionnaire de tous les états de l'ensemble des acteurs. Zones : StateID (unique parmi tous les acteurs), Name, Description, Note, SourceFileID, ActorID, TypeID, KindOfState (0 - simple, 1 dérivé, 2 état d expression, 3 lien, 4 - état d expression généré pour un opérateur de cumulation ou de tabulation), LanguageID, ContextID Tableau : ActorStateDependencyDic Description : Dictionnaire des dépendances d'état. Zones : StateID, DependentStateID Tableau : ActorUnknownStateDic Description : Dictionnaire des états d'acteur inconnus survenus pendant la création de la liste des états lus/fixés par une fonction ou un événement. La situation peut s'expliquer par des expressions complexes de pointeur qui font appel aux états d'acteur. Zones : StateID, Name Tableau : ActorEventDic Description : Dictionnaire de tous les événements de l'ensemble des acteurs. Zones : ActorID, EventID, WaitFnName, ImplementFnName, Note, SourceFileID (de la déclaration), LanguageID, ContextID Tableau : ActorEventStateDic Description : Dictionnaire des états d'entrée de tous les événements relatifs aux acteurs. Zones : ActorID, EventID, StateID Tableau : ActorEventStateReadDic Description : Dictionnaire de tous les états lus par la fonction d'application de l'ensemble des événements relatifs aux acteurs. Zones : ActorID, EventID, StateReadID Tableau : ActorEventStateSetDic Description : Dictionnaire de tous les états fixés par la fonction d'application de l'ensemble des événements relatifs aux 186 Matériel de référence Guide du concepteur de Modgen v10.1.0

195 acteurs. Zones : ActorID, EventID, StateSetID Tableau : ActorFunctionDic Description : Dictionnaire de toutes les fonctions relatives aux acteurs (à l'exception des événements). Zones : ActorID, FunctionID, Name, Description, Note, SourceFileID (de la déclaration), Declaration, LanguageID, ContextID Tableau : ActorFunctionStateReadDic Description : Dictionnaire de tous les états lus par l'ensemble des fonctions relatives aux acteurs. Zones : ActorID, FunctionID, StateReadID Tableau : ActorFunctionStateSetDic Description : Dictionnaire de tous les états fixés par l'ensemble des fonctions relatives aux acteurs. Zones : ActorID, FunctionID, StateSetID Tableau : ActorFunctionHookedFunctionDic Description : Dictionnaire de tous les crochets de fonction aux fonctions relatives aux acteurs. Zones : ActorID, FunctionID, HookedFunctionID Tableau : ActorEventHookedFunctionDic Description : Dictionnaire de tous les crochets de fonction aux événements relatifs aux acteurs. Zones : ActorID, EventID, HookedFunctionID Tableau : ActorLinkDic Description : Dictionnaire des liens entre les acteurs. Zones : ActorID, LinkID, TypeID, Name, Description, Note, SourceFileID, Single (Yes/ No), LinkedActorID, LinkedLinkID, LanguageID, ContextID Tableau : TableDic Description : Dictionnaire de tous les tableaux de sortie. Zones : TableID, Name, Description, Note, SourceFileID, ActorID, Rank, AnalysisDimensionPosition, AnalysisDimensionName, AnalysisDimensionDescription, AnalysisDimensionNote, Sparse, LanguageID, ContextID Guide du concepteur de Modgen v Matériel de référence 187

196 Tableau : TableClassDimDic Description : Dictionnaire de toutes les dimensions de classification pour l'ensemble des tableaux. Zones : TableID, Position, StateID, Name, Description, Note, TypeID, Totals (Yes/No), LanguageID Tableau : TableExpressionDic Description : Dictionnaire de toutes les expressions de l'ensemble des tableaux. Zones : TableID, ExpressionID, Name, Description, Note, ExpressionString, Scale, Decimals, LanguageID, DescGenerated Voici les valeurs de «DescGenerated» et leur signification. (. Cette information est utilisée principalement pour des outils qui utilisent la base de données de documentation pour faciliter la traduction d un modèle dans une autre langue. ) 0 = l étiquette a été précisée dans le code (dans cette langue) 1 = l étiquette a été générée par Modgen (ex. pour un état simple, l étiquette est le nom de l état) 2 = l étiquette a été générée par Modgen en utilisant l étiquette précisée dans le code pour une autre langue 3 = l étiquette a été générée par Modgen en utilisant l étiquette d un état dans la bonne langue 4 = l étiquette a été générée par Modgen en utilisant l étiquette d un état dans une autre langue 5 = l étiquette a été générée par Modgen en utilisant l étiquette générée par Modgen pour un autre état Des étiquettes descriptives sont créées par Modgen dans l ordre suivant: S il y a une étiquette pour une dimension, alors «DescGenerated» est 0. S il n y a pas d étiquette pour la dimension dans la bonne langue, mais qu il y en a pour la dimension dans la langue par défaut, alors cette étiquette est affichée et «DescGenerated» est 2. S il n y a pas d étiquette dans la langue voulue ni dans la langue par défaut, alors : o S il y a une étiquette pour l état dans la langue voulue, cette étiquette est utilisée et «DescGenerated» est 3, si ce n est pas une étiquette générée. 188 Matériel de référence Guide du concepteur de Modgen v10.1.0

197 o Si c est une étiquette générée, «DescGenerated» est 5. S il n y a pas d étiquette pour l état dans la langue voulue, alors l étiquette pour la langue par défaut est utilisée : o o «DescGenerated» est 4 si l étiquette n a pas été générée par Modgen «DescGenerated» est 5 si l étiquette a été générée par Modgen Tableau : TableRefStateDic Description : Dictionnaire de tous les états indiqués dans l'ensemble des tableaux. Zones : TableID, StateID Tableau : TableGroupDic Description : Dictionnaire de tous les groupes de tableaux. Zones : TableGroupID, Name, Description, Note, LanguageID, ContextID Tableau : TableGroupMemberDic Description : Dictionnaire de tous les membres de l'ensemble des groupes de tableaux. Zones : TableGroupID, Position, TableID, MemberGroupID Tableau : TableSheetDic Description : Noms de toutes les feuilles Excel de MS pour tous les tableaux non exclus. Ce tableau figure uniquement de façon temporaire et sera probablement supprimé dans les versions à venir de Modgen. Zones : TableID, SheetID, SheetName Tableau : ModuleDic Description : Dictionnaire de tous les fichiers source (habituellement des fichiers.mpp) comportant des notes jointes. Ce tableau était autrefois appelé «SourceFileDic». Pour des raisons de compatibilité avec des versions antérieures, le tableau SourceFileDic est préservé dans la base de données de documentation. Zones : SourceFileID, FileName, FileNote, LanguageID, ContextID Tableau : UserTableDic Guide du concepteur de Modgen v Matériel de référence 189

198 Description : Dictionnaire de tous les tableaux d'utilisateurs. Zones : TableID (débute à 1 000), Name, Description, Note, SourceFileID, Rank, AnalysisDimensionPosition, AnalysisDimensionName, AnalysisDimensionDescription, AnalysisDimensionNote, Sparse, LanguageID, ContextID Tableau : UserTableClassDimDic Description : Dictionnaire de toutes les dimensions de classification des tableaux d'utilisateur. Zones : TableID, Position, Name, Description, Note, TypeID, Totals (Yes/No), LanguageID Tableau : UserTableExpressionDic Description : Dictionnaire de toutes les expressions des tableaux d'utilisateur. Zones : TableID, ExpressionID, Name, Description, Note, Scale, Decimals, LanguageID, DescGenerated Voici les valeurs de «DescGenerated» et leur signification. (. Cette information est utilisée principalement pour des outils qui utilisent la base de données de documentation pour faciliter la traduction d un modèle dans une autre langue. ) 0 = l étiquette a été précisée dans le code (dans cette langue) 1 = l étiquette a été générée par Modgen (ex. pour un état simple, l étiquette est le nom de l état) 2 = l étiquette a été générée par Modgen en utilisant l étiquette précisée dans le code pour une autre langue 3 = l étiquette a été générée par Modgen en utilisant l étiquette d un état dans la bonne langue 4 = l étiquette a été générée par Modgen en utilisant l étiquette d un état dans une autre langue 5 = l étiquette a été générée par Modgen en utilisant l étiquette générée par Modgen pour un autre état Des étiquettes descriptives sont créées par Modgen dans l ordre suivant: S il y a une étiquette pour une dimension, alors «DescGenerated» est 0. S il n y a pas d étiquette pour la dimension dans la bonne langue, mais qu il y en a pour la dimension dans la langue par défaut, alors cette étiquette est affichée et «DescGenerated» est 2. S il n y a pas d étiquette dans la langue voulue ni dans la langue par défaut, alors : o S il y a une étiquette pour l état dans la langue voulue, cette étiquette est utilisée et «DescGenerated» est 3, si ce n est pas une 190 Matériel de référence Guide du concepteur de Modgen v10.1.0

199 étiquette générée. o Si c est une étiquette générée, «DescGenerated» est 5. S il n y a pas d étiquette pour l état dans la langue voulue, alors l étiquette pour la langue par défaut est utilisée : o o «DescGenerated» est 4 si l étiquette n a pas été générée par Modgen «DescGenerated» est 5 si l étiquette a été générée par Modgen Contenu de la base de données des sorties Modgen La base de données des sorties Modgen est une base de données MS Access qui renferme les tableaux suivants : Tableau : VersionInfo Description : Version du fichier. Zones : Version Tableau : LanguageDic Description : Dictionnaire des langues, voir la base de documentation. Renferme la liste des langues supportées et des traductions de certains mots créés par Modgen dans les sorties. Zones : LanguageID, LanguageCode, LanguageName, All, Min, Max Tableau : ModelInfoDic Description : Diverses zones actuellement trouvées dans la zone ModelInfo de la feuille Contents. La zone LanguageID est requise pour la zone CompletionStatus multilingue. Zones : Time, Directory, CommandLine, CompletionStatus, Subsamples (number), CV (Y/N), SE(Y/N), LanguageID Tableau : TableDic Description : Liste des tableaux de sortie non exclus. Zones : TableID, Name, Description, Note, Rank, AnalysisDimensionPosition, AnalysisDimensionName, AnalysisDimensionDescription, AnalysisDimensionNote, Sparse, LanguageID Guide du concepteur de Modgen v Matériel de référence 191

200 Tableau : TableClassDimDic Description : Liste des dimensions de classification pour l'ensemble des tableaux de sortie. Zones : TableID, Position, Name, Description, Note, TypeID, Totals (Y/N), LanguageID Tableau : TableExpressionDic Description : Liste des expressions utilisées dans tous les tableaux de sortie. Zones : TableID, ExpressionID, Name, Description, Note, Decimals, LanguageID Tableau : UserTableDic Description : Dictionnaire de tous les tableaux d'utilisateur. Zones : TableID (débute à 1 000), Name, Description, Note, Rank, AnalysisDimensionPosition, AnalysisDimensionName, AnalysisDimensionDescription, AnalysisDimensionNote, Sparse, LanguageID Tableau : UserTableClassDimDic Description : Dictionnaire de toutes les dimensions de classification des tableaux d'utilisateur. Zones : TableID, Position, Name, Description, Note, TypeID, Totals (Yes/No), LanguageID Tableau : UserTableExpressionDic Description : Dictionnaire de toutes les expressions des tableaux d'utilisateur. Zones : TableID, ExpressionID, Name, Description, Note, Decimals, LanguageID Tableau : <table_name> Description : Les données réelles du tableau de sortie indiqué par <table_name> (tableau ordinaire ou d'utilisateur). Zones : Dim0,..., DimN, Value, CV, SE Si la simulation a été exécutée avec plus d'un sous-échantillon et s'il ne s'agit pas d'un modèle de cellule, des zones additionnelles contenant des valeurs de sous-échantillon sont présentes : Value0, Value1,, ValueM, M correspondant au nombre de sous-échantillons moins un. Tableau : ParameterDic Description : Liste des paramètres de sortie. Zones : ParameterID, Name, Description, Note, ValueNote, DataFileID,, TypeID, Rank, LanguageID Tableau : ParameterDimensionDic Description : Liste des dimensions pour tous les paramètres de sortie. 192 Matériel de référence Guide du concepteur de Modgen v10.1.0

201 Zones : ParameterID, DisplayPosition, TypeID Tableau : <parameter_name > Description : Les données réelles du paramètre de sortie indiqué par <parameter_name>. Zones : Dim0,..., DimN, Value Tableau : TypeDic Description : Liste de tous les types utilisés par les tableaux de sortie et (ou) les paramètres de sortie. Zones : TypeID, DicID (0 - SimpleTypeDic, 1 - LogicalDic, 2 - ClassificationDic, 3 - RangeDic, 4 - PartitionDic, 5 - LinkTypeDic) Tableau : SimpleTypeDic Description : Liste des types de données simples utilisés par les tableaux de sortie et (ou) les paramètres de sortie. Zones : TypeID, Name Tableau : LogicalDic Description : Contient les valeurs et les descriptions associées au type logical. Zones : TypeID, Name, Value, ValueName, ValueDescription, LanguageID Tableau : ClassificationDic Description : Liste des classifications utilisées par les tableaux de sortie et (ou) les paramètres de sortie. Zones : TypeID, Name, Description, Note, NumberOfValues, LanguageID Tableau : AggregationDic Description : Dictionnaire de toutes les agrégations. Zones : Name, AggregatedClassificationID, DetailedClassificationID Tableaux d'agrégation (nommés en fonction de l'aggregationdic) Description : Mappage détaillé d'une agrégation particulière. Zones : DetailedValue, AggregatedValue Tableau : ClassificationValueDic Guide du concepteur de Modgen v Matériel de référence 193

202 Description : Liste de tous les membres de classification. Zones : TypeID, EnumValue, Name, Description, Note, LanguageID Tableau : RangeDic Description : Liste des fourchettes utilisées par les tableaux de sortie et (ou) les paramètres de sortie. Zones : TypeID, Name, Description, Note, Min, Max, LanguageID Tableau : PartitionDic Description : Liste des partitions utilisées par les tableaux de sortie et (ou) les paramètres de sortie. Zones : TypeID, Name, Description, Note, NumberOfValues, LanguageID Tableau : PartitionValueDic Description : Liste des points de rupture de toutes les partitions. Zones : TypeID, Position, Value, StringValue Tableau : LinkTypeDic Description : Liste des types de lien utilisés par les tableaux de sortie et (ou) les paramètres de sortie. Zones :TypeID, Name, LinkedActorID Tableau : DataFileDic Description : Notes de fichier pour tous les fichiers de données. Zones : DataFileID, FileName, FileNote, LanguageID Contenu de la base de données de suivi Modgen La présente annexe décrit la version du fichier de la base de données de suivi. Tous les tableaux, sauf le tableau Historique de cette base de données sont identiques, de par leur structure, aux tableaux figurant dans la base de données de documentation de Modgen (reportez-vous à la section «Contenu de la base de données de documentation de Modgen») Dans la base de données de suivi, les tableaux peuvent comporter un nombre moindre de zones et d'enregistrements, selon l'instruction de suivi Modgen qui a été utilisée pour la création de la base de données. Le tableau Historique renferme les données de tous les états observés. Ses zones sont les suivantes : 194 Matériel de référence Guide du concepteur de Modgen v10.1.0

203 ObjectID un entier long Time un nombre double StateID un entier long Value un nombre double SequenceCnt un entier long (aucune répétition dans les enregistrements). Le BioBrowser de Modgen se sert d'interrogations SQL pour la consultation du tableau Historique, afin de constituer l'affichage graphique. Pour optimiser le temps de réponse des interrogations du BioBrowser, Modgen définit des indices pour ce tableau d'après les zones ObjectId/ StateId, à titre d'indice combiné, et d'après la zone SequenceCnt comme indice distinct. Modgen respecte les règles suivantes pour la création du fichier de suivi : Une instance d'un acteur est désignée de façon unique par une valeur ObjectID du tableau Historique. Pour chaque objet, un enregistrement n'est adjoint au tableau Historique, pour chaque état faisant l'objet d'un suivi, que si la valeur de cet objet change. Dans le cas d'événements simultanés (mêmes zones ObjectID, Time et StateID, mais zone Value différente), la zone SequenceCnt détermine l'ordre d'affichage par le BioBrowser. Chaque acteur doit comporter un état logique dont la valeur Name est «tracking» dans le dictionnaire d'état ActorStateDic. Il s'agit d'un état généré par Modgen (un état généré par l'utilisateur ne peut pas porter le nom «tracking»). Précisons que la zone «Name» du tableau ActorStateDic est un identificateur de programmation d'un état et qu'il est indépendant de la langue (à la différence de zones Description et Note de ce même tableau). Chaque acteur comprend un état généré à l'interne et dont la valeur Name est «case_id». Cet état ne peut pas être affiché par le BioBrowser (autrement dit, il ne s'agit pas d'un état offert à la fenêtre de dialogue Ajouter/insérer des états). Un état généré par l'utilisateur ne peut pas porter le nom «case_id». Dans le cas des types d'état simples, la zone Value contient la valeur de cet état au moment indiqué par la zone Time. Pour les classifications, elle renferme la valeur EnumValue qui figure dans le tableau ClassificationValueDic. Pour les états logiques, elle comprend la zone Value du tableau LogicalDic. Pour les plages, elle comporte un nombre entier figurant entre les valeurs Min et Max (inclusivement) du tableau RangeDic. Les tableaux PartitionDic et PartitionValueDic du fichier de suivi sont toujours vides (les états axés sur les partitions sont toujours écrits sous forme de nombres entiers dans le fichier de suivi, le nombre entier indiquant la position dans la partition). La zone Value des états Link est décrite ci-après. Chaque état qui fait l'objet d'un suivi (sauf les états de lien) doivent comporter une valeur le plus tôt possible lorsque le suivi est activé. Sur la commande de la zone SequenceCnt, l'état du suivi sera premier et dernier pour tous les états de cette instance de l'acteur. Sa valeur est de 1 lorsque le suivi débute et de 0 à la fin du suivi. Chaque interrogation du BioBrowser contient l état du suivi ainsi que l'état demandé (ainsi, le Guide du concepteur de Modgen v Matériel de référence 195

204 Rapport sur l utilisation de mémoire BioBrowser est en mesure de décomposer le graphique lorsque l'état de suivi est activé et désactivé). Le BioBrowser trie les interrogations du tableau Historique d'après la zone SequenceCnt plutôt qu'en fonction de la zone Time, car un trop grand nombre d'associations sont définies pour la zone Time. Chaque zone StateID du dictionnaire d'états d'acteur et chaque zone LinkID du dictionnaire de liens d'acteur doivent être uniques pour tous les acteurs. Ainsi, si un acteur «personne» et un acteur «enfant» comportent tous deux un état appelé Gender, ils comprendront chacun leur propre enregistrement et une valeur StateID unique dans le dictionnaire d'états. En outre, les LinkID du tableau ActorLinkDic ne doivent pas être identiques à une des valeurs StateID du tableau ActorStateDic. Tous les dictionnaires comprenant du texte tributaire d'une langue renferment un enregistrement pour chaque langue précisée dans le tableau LanguageDic. Les états Link sont spéciaux : la zone StateID du tableau Historique contient la valeur LinkID de cet état relié du tableau ActorLinkDic. De plus, leur zone de valeur contient un pointeur (ObjectID) qui désigne l'objet visé par le lien. La zone Value d'un état relié ne contient que l'élément -/+ObjectID. Il s'agit du seul type d'état qui ne contient aucune valeur dans le tableau Historique dès le début du suivi. La zone Value renferme l'élément ObjectID lorsque cet objet relié est ajouté pour la première fois et ObjectID lorsque l'état visé par le lien est supprimé. Pendant la simulation, une utilisation importante de mémoire viendra normalement de quatre sources différentes : les paramètres, la mémoire utilisée pour conserver les acteurs, la queue d événements, et les tableaux. Paramètres Les paramètres ne grossissent pas en traille durant la simulation, mais peuvent quand même utiliser une quantité de mémoire importante s ils contiennent de nombreuses cellules. Ceci est un problème seulement au début de la phase de simulation si les cellules ne sont pas référencées répétitivement. Par exemple, un gros fichier de microdonnées représenté comme un paramètre ne causera pas de problèmes s il n est lu qu une seule fois au début de la simulation, parce que le système d exploitation utilise la pagination pour de la mémoire qui n est pas souvent référencée. Si la machine a 2 GB ou plus de mémoire physique, la mémoire utilisée pour les paramètres peut réduire la quantité de mémoire disponible pendant la simulation parce que la pagination ne peut pas augmenter la quantité de mémoire disponible au-delà de la limite pour les adresses de 2 GB pour les processeurs 32-bit. Mémoire utilisée pour les acteurs La mémoire utilisée est le produit du nombre d acteurs et (approximativement) du nombre d états. Le type d état est également important, puisqu un état d un type à point flottant prend 8 octets alors que d autres états ne prennent que 4 octets. Des états cachés internes associés aux tableaux sont également présents dans les acteurs. 196 Matériel de référence Guide du concepteur de Modgen v10.1.0

205 Queue d événements La mémoire utilisée est le produit du nombre d acteurs et du nombre d événements (pour chaque type d acteur) multiplié par la taille de la structure interne utilisée pour les événements (une quantité qui ne dépend pas du modèle). Tableaux Les tableaux utilisent de la mémoire pour les états internes créés pour chaque acteur, ainsi que pour l endroit commun utilisé pour cumuler les résultats. L endroit commun utilisé pour les tableaux peut être large si les tableaux ont de nombreuses cellules, et si ces cellules sont répétitivement mises à jour pendant la phase de simulation. L endroit où sont conservées les cellules des tableaux est alloué seulement pour les tableaux qui ont été sélectionnés par l utilisateur dans le scénario, alors que les états internes créés pour les tableaux dans les acteurs sont présents que le tableau même si le tableau n était pas sélectionné. L espace utilisé pour les cellules des tableaux dépend également du nombre de souséchantillons ou de réitérations. Ensembles d acteurs La mémoire utilisée est (approximativement) le produit du nombre d acteurs dans l ensemble d acteurs et la taille de la structure interne utilisée pour conserver les références aux acteurs dans l ensemble d acteurs. Des états internes cachés peuvent également être créés pour les ensembles d acteurs pour chaque acteur, membre de l ensemble d acteurs ou non. Le rapport sur l utilisation de mémoire identifie des domaines que le concepteur de modèle ou l utilisateur peut changer. L emphase est mise sur les tableaux puisque l élimination d un tableau est un moyen facile pour un concepteur de modèle de libérer de la mémoire sans changer la structure du modèle. Une nouvelle case à cocher a été ajoutée au dialogue «Mise en place du scénario» intitulée «Rapport sur l utilisation de mémoire» dans l terface visuelle à Modgen.. Lorsque cette case est cochée, un rapport sur l utilisation de mémoire sera généré dans un fichier du nom nom_de_scénario(usage).htm. Ce rapport est généré à la fin de la simulation, dans la langue de l interface du modèle lors de la création du rapport. Il est à noter que le nom du fichier est le même en anglais et en français. Pour les simulations distribuées, seules les statistiques de la tâche «maître» finale (celle qui rassemble les résultats) seront conservées sous le nom de scénario «maître». Chaque section du rapport est expliquée ci-dessous. Information générale La première section du rapport contient de l information générale au sujet de la simulation : date, exécutable, version, scénario, nombre de sous-échantillons ou réitérations, nombre de copies des tableaux et nombre de fils d exécution. Le nombre de fils d exécution correspond au nombre réel de fils utilisés pour la simulation. Par exemple, si un utilisateur précise un nombre de fils d exécution plus grand que le nombre de sous-échantillons ou réitérations, le nombre réel de fils d exécution sera égal au nombre de sous-échantillons ou réitérations. Le nombre de copies des tableaux est là parce que Modgen garde une copie des cellules des tableaux pour chaque sous-échantillon ou réitération. Pour les modèles de Guide du concepteur de Modgen v Matériel de référence 197

206 cas, une copie des cellules des tableaux est également conservée pour la simulation entière. Le nombre de copies des tableaux est utilisé pour calculer l utilisation de mémoire des tableaux. Nombre maximal d instances Après la section contenant l information générale se trouve un tableau contenant le nombre maximal d instances des acteurs par nom d acteur déclaré dans le modèle (ex. Person). Pour des raisons pratiques, ce nombre est en fait la somme du nombre maximal d acteurs «actifs» dans chaque fil d exécution pendant la simulation. Ce nombre est utilisé pour calculer l utilisation de mémoire des acteurs. Paramètres Le tableau suivant rapporte l utilisation de mémoire des paramètres. Chaque paramètre est présent dans le tableau en ordre alphabétique. Pour chaque paramètre, le nombre d octets utilisé est donné. La mémoire utilisée par un paramètre est le multiple du nombre de cellules du paramètre et du nombre d octets utilisé pour une cellule du paramètre. La mémoire utilisée pour une cellule du paramètre dépend du type du paramètre. La quantité de mémoire utilisée pour chaque type de paramètre est donnée à la fin du rapport. Acteurs et événements Le troisième tableau est intitulé «Tableau 3 : Utilisation de mémoire : Acteurs et événements». Il y a en fait dans cette section un tableau par catégorie d acteurs (ex. Person). Pour chaque acteur, l utilisation de mémoire est séparée par module. Il y a dans chaque tableau une rangée pour chaque module dans lequel de la mémoire est utilisée pour les acteurs et/ou les événements. Chaque rangée contiendra les informations suivantes : États déclarés (octets par acteur) Ceci est la mémoire utilisée pour les états déclarés par le concepteur de modèle dans le module. C est calculé pour un acteur seulement. Par exemple, si le fichier PersonCore.mpp contient la déclaration suivante: actor Person { SEX sex; }; La mémoire utilisée pour l état «sex» sera comptée dans la rangée du module «PersonCore». États internes (octets par acteur) Ceci est la mémoire utilisée par les états créés par Modgen pour les états dérivés déclarés dans le module. C est calculé 198 Matériel de référence Guide du concepteur de Modgen v10.1.0

207 pour un seul acteur. Par exemple, si le fichier PersonCore.mpp contient la déclaration suivante : actor Person { int person_year = duration(life_status,alive); }; La mémoire utilisée pour l état «person_year» serait comptée dans les états déclarés du module «PersonCore». Par contre, lorsqu un concepteur de modèle utilise un état dérivé «duration( )», Modgen créé automatiquement un ou plusieurs «états internes» qui utilisent également de la mémoire. Cette utilisation de mémoire serait comptée dans les états internes du module «PersonCore». La quantité maximale de mémoire utilisée pour les états internes pour chaque type d état dérivé est indiquée à la fin du rapport. Liens (moyenne d octets par acteur) Ceci est la mémoire utilisée pour les liens déclarés dans le module. Pour un lien simple, la quantité de mémoire utilisée est la même pour tous les acteurs. C est cette quantité qui est exprimée ici. Pour un lien multiple, la mémoire utilisée dépend du nombre d acteurs liés. Pour chaque lien multiplie différent, le nombre maximal d acteurs liés est conservé en mémoire pendant la simulation et une moyenne est calculée en prenant le nombre maximal d acteurs liés divisé par le nombre maximal d acteurs actifs tel que donné dans le tableau «Nombre maximal d instances». Mémoire totale pour les acteurs (octets) La mémoire totale utilisée pour les acteurs en octets est la somme des trois premières colonnes, multipliée par le nombre maximal d acteurs actifs pendant la simulation, tel que donné dans le tableau «Nombre maximal d instances». Fonctions d événements (nombre) Ceci est le nombre d événements déclarés pour cet acteur dans le module. Par exemple, si le fichier PersonCore.mpp contient la déclaration : actor Person { event timeschoolyearevent,schoolyearevent, 2; event timeschoolentryevent,schoolentryevent, 1; event timeelsecdropoutevent,elsecdropoutevent, 1; event timeelsecreturnevent,elsecreturnevent, 1; }; Guide du concepteur de Modgen v Matériel de référence 199

208 alors la colonne indiquerait que 4 fonctions d événements sont déclarées pour l acteur Person dans le module «PersonCore». Mémoire totale pour les événements (octets) Pour un acteur, la mémoire utilisée en octets pour les événements correspond à la mémoire utilisée pour un seul événement, multiplié par le nombre de fonctions d événements déclarés dans ce module. Dans cette colonne est indiquée la quantité totale de mémoire utilisée pour les événements, c est-à-dire la mémoire utilisée pour les événements pour un acteur multipliée par le nombre maximal d acteurs actifs tel que donné dans le tableau «Nombre maximal d instances». Mémoire Totale (octets) Ceci est la somme de la mémoire totale utilisée pour les événements et de la mémoire totale utilisée pour les acteurs. Tableaux Le tableau suivant rapporte la mémoire utilisée pour les tableaux. Chaque tableau est présenté en ordre alphabétique. Pour chaque tableau, la rangée contient l information suivante : Tableau sélectionné La mémoire utilisée pour les cellules du tableau est utilisée seulement si le tableau est sélectionné dans le scénario par l utilisateur. Cette colonne contiendra un «X» si le tableau était inclus dans la simulation et sera vide sinon. Cellules du tableau (octets) Ceci est la mémoire utilisée pour une copie des cellules du tableau, si le tableau est inclus dans la simulation. (À ne pas oublier que plusieurs copies des cellules du tableau sont conservées). Cette information est présente même si le tableau n était pas inclus dans la simulation. États internes (octets par acteur) pour tableaux Ceci est la mémoire utilisée pour les états créés par Modgen pour les états dérivés déclarés dans le tableau. C est calculé pour un acteur seulement. Par exemple, si la déclaration du tableau est : table Person X03_SeverelyDisabled { { entrances( dfle, SEVERE_DIS ) } }; 200 Matériel de référence Guide du concepteur de Modgen v10.1.0

209 Modgen créera un état interne pour l état dérivé «entrances(dfle, SEVERE_DIS)». La mémoire utilisée pour cet état interne serait comptée dans cette colonne du tableau. Modgen crée également des états internes pour le tableau lui-même. La mémoire utilisée pour ces états est comptée dans cette colonne également. La quantité de mémoire utilisée pour les états internes pour le tableau lui-même est indiquée à la fin du rapport. Cette mémoire sera utilisée même si le tableau n est pas sélectionné. Mémoire totale pour les états internes (octets) pour tableaux Ceci correspond à la mémoire utilisée pour les états internes pour un acteur multipliée par le nombre maximal d acteurs actifs tel que donné dans le tableau «Nombre maximal d instances». Total (octets) pour tableaux Ceci est la quantité totale de mémoire utilisée pour le tableau. Si le tableau n était pas inclus dans la simulation, alors la mémoire totale est égale à la mémoire totale utilisée pour les états internes. Par contre, si le tableau était inclus dans la simulation, alors la mémoire utilisée pour une copie des cellules du tableau, multipliée par le nombre de copies des cellules que Modgen garde, est additionnée à la mémoire totale pour les états internes. Résumé par module La section suivante est un résumé de l utilisation de mémoire par module. Chaque module est présent dans le tableau en ordre alphabétique. Pour chaque rangée, la mémoire utilisée pour les paramètres, les acteurs et événements, et les tableaux déclarés dans le module est indiquée. Ensembles d acteurs Si le modèle ne contient aucun ensemble d acteur, ce tableau n apparaîtra pas dans le rapport. Si le modèle contient des ensembles d acteurs, ce tableau indiquera l utilisation de mémoire de chacun de ces ensembles d acteurs. Chaque ensemble d acteur est présent dans le tableau en ordre alphabétique. Pour chaque ensemble d acteurs, l information suivante est fournie : Nombre maximal de membres Ceci est le nombre maximal de membres que l ensemble d acteurs a eu pendant la simulation. Membres (octets) Une partie de la mémoire utilisée pour un ensemble d acteurs dépend de l appartenance des acteurs à l ensemble Guide du concepteur de Modgen v Matériel de référence 201

210 d acteurs. Pour chaque acteur membre d un ensemble, de la mémoire est utilisée pour conserver la position de l acteur dans l ensemble, etc. C est cette utilisation de mémoire qui est indiquée ici. La quantité de mémoire rapportée dans cette colonne correspond au multiple du nombre maximal de membres de l ensemble et de la quantité de mémoire utilisée pour un acteur membre de l ensemble. La quantité de mémoire utilisée pour un acteur membre d un ensemble d acteurs est donnée à la fin du rapport. États internes (octets par acteur) pour ensembles d acteurs Selon la déclaration de l ensemble d acteurs, il est possible que des états internes soient créés par Modgen pour l ensemble. Par exemple, si la déclaration de l ensemble d acteurs est : actor_set Host asallhosts order RandomStream(); alors un état interne est créé dans l acteur «Host» pour conserver le nombre aléatoire associé avec l acteur membre de l ensemble d acteurs. Il est également possible que des états dérivés soient déclarés dans un ensemble d acteurs, comme c est le cas pour les tableaux. La mémoire utilisée pour ces états internes est rapportée ici. C est calculé pour un acteur seulement. Cette mémoire est utilisée même si l acteur n est jamais membre de l ensemble d acteur. Mémoire totale pour les états internes (octets) Ceci est la mémoire utilisée pour les états internes d un acteur, multipliée par le nombre maximal d acteurs actifs tel que donné dans le tableau «Nombre maximal d instances». À noter que la mémoire utilisée pour les états internes est multipliée par le nombre maximal d acteurs actifs, et non le nombre maximal de membres de l ensemble, parce que cette mémoire est utilisée même si l acteur n est jamais membre de l ensemble. Cellules de l ensemble d acteurs (octets) Ceci est le nombre de cellules de l ensemble d acteurs multiplié par la mémoire utilisée pour une cellule d un ensemble d acteur. Cette mémoire est utilisée même si l ensemble d acteurs est vide. La quantité de mémoire utilisée par une cellule d un ensemble d acteur est donnée à la fin du rapport. Total (octets) Ceci est la somme de la mémoire utilisée pour les membres, pour les états internes et pour les cellules de l ensemble d acteurs. Résumé Le dernier tableau du rapport est un résumé. Dans ce tableau, la mémoire totale utilisée par les paramètres, les acteurs et 202 Matériel de référence Guide du concepteur de Modgen v10.1.0

211 événements, les ensembles d acteurs et les tableaux est rapportée. Annexe A Taille des états et des paramètres Il y a trois annexes après les tableaux rapportant l utilisation de mémoire. La première annexe est une liste des différents types et de la mémoire utilisée par un état ou une cellule d un paramètre de ce type. Par exemple, un état déclaré avec le type «int» utilisera 4 octets de mémoire, alors qu un état de type «double» en utilisera 8. La taille du type «TIME» dépend de la déclaration de ce type dans le modèle. Par exemple, notre modèle exemple Simpex a la déclaration suivante : time_type int; Cela signifie qu un état déclaré de type «TIME» utilisera la même quantité de mémoire qu un état déclaré de type «int», c est-à-dire 4 octets. Annexe B états internes Pour chaque fonction d état dérivé, le nombre maximal d octets utilisés pour les états internes est indiqué. Par exemple, Modgen créé un état interne de type «int» pour chaque état dérivé «changes» (ex. changes(dfle)). Dans certains cas, le nombre et le type des états internes créés par Modgen dépendent du contexte. Par exemple, Modgen créé 2 états internes de type «double» et un 1 état interne de type «TIME» pour un état dérivé «weighted_duration» si ce dernier est utilisé dans la déclaration d un état. Si, par contre, l état «weighted_duration» n est utilisé qu à l intérieur d un tableau, alors Modgen créé seulement 1 état interne de type «double» et 1 état interne de type «TIME». C est pour cette raison que le nombre d octets indiqué est un maximum. Le nombre d états internes créés pour les tableaux est également donné dans cette annexe. Annexe C structures Cette annexe fournit une liste des différentes structures utilisées dans le rapport et donne, pour chacune d entre elle, la mémoire utilisée par la structure elle-même. Cette taille incorpore l effet de packing_level, mais contrairement au tableau 3 «L utilisation de mémoire des acteurs et évènements», ça ne comprend pas l utilisation dynamique de mémoire par des acteurs, ex. la mémoire utilisée pour des liens multiples entre des acteurs. Fichier de journalisation du modèle Guide du concepteur de Modgen v Matériel de référence 203

212 Changements apportés au fichier de journalisation du modèle Information sur la simulation Le fichier de journalisation produit par les modèles Modgen contient l heure à laquelle la simulation a été lancée, ainsi que certains renseignements sur les caractéristiques du poste de travail, comme le nom de l ordinateur, le nom de l utilisateur, le nombre de processeurs et le modèle des processeurs. La présence de cette information peut dépendre du système d exploitation. En cas de blocage ou d arrêt imprévu du modèle, le fichier de journalisation peut contenir des données susceptibles d aider l équipe de conception de modèles Modgen à repérer la cause du problème. Ces données diagnostiques sont supprimées automatiquement du fichier de journalisation quand l exécution du modèle est achevée avec succès. La fréquence d horloge du processeur central est également inscrite dans le fichier de journalisation du modèle. Statistiques de performance Toutes les statistiques de performance pour la simulation entière sont écrites à la fin du fichier de journalisation. Les statistiques de performance actuelles sont écrites périodiquement dans le fichier de journalisation. Cette information est écrite approximativement chaque fois que 10% de la simulation est exécutée. Si une simulation est très rapide, cette information sera écrite moins souvent. Version de Modgen et du modèle Des lignes supplémentaires sont écrites dans le fichier log du scénario qui rapportent la version de Modgen, le nom du modèle, et la version du modèle, ex. : Version de Modgen Nom du modèle : simpex Version du modèle : Matériel de référence Guide du concepteur de Modgen v10.1.0

213 Annexe: Modgen et l environnement Visual Studio 2008 Configuration de Visual Studio 2008 pour les applications Modgen 10 Modgen 10 a été développé à l aide de Visual Studio 2008, et vous devrez avoir installé Visual Studio 2008 sur votre machine afin de pouvoir compiler vos modèles Modgen 10. En fait, Visual Studio 2008 devrait toujours avoir été installé avant l installation de Modgen 10. Si ce n est pas le cas, le dialogue suivant apparaîtra : Guide du concepteur de Modgen v Annexe: Modgen et l environnement Visual Studio

214 Lorsque Visual Studio 2008 et Modgen 10 sont installés, dans cet ordre, sur une machine, Visual Studio 2008 est configuré automatiquement par le programme d installation de Modgen 10 pour fonctionner avec les applications Modgen Annexe: Modgen et l environnement Visual Studio 2008 Guide du concepteur de Modgen v10.1.0

215 Conversion de modèles Modgen à Visual Studio 2008 Si vous avez un modèle créé avec Modgen 9, le projet correspondent devra être converti à Visual Studio 2008 pour que le modèle puisse être compilé. Cette section explique comment convertir à Visual Studio 2008 des projets de modèles créés ou mis à jour avec Visual Studio Avant de commencer la conversion, prenez une copie de sauvegarde de votre modèle. Une fois la conversion complétée, il ne sera plus possible de faire marche arrière. La seule façon alors de ramener le projet à un format utilisable par Visual Studio 2005, et donc de compiler avec une ancienne version de Modgen, serait de recréer le projet en entier. Démarrez Visual Studio Choisissez «Open» ensuite «Project/Solution» du menu «File». Dans le dialogue «Open project», naviguez jusqu au répertoire de votre modèle et choisissez le fichier de solution (.sln) de votre modèle. Cela démarrera l assistant de conversion Visual Studio : Notez que vous ne pouvez pas choisir de double-cliquer sur le fichier de solution plutôt que de l ouvrir de cette façon, du moins si vous avez Visual Studio 2005 et Visual Studio 2008 installés sur votre machine. Cliquez «Next» pour procéder. L assistant vous demandera si vous voulez créer une copie de sauvegarde de votre Guide du concepteur de Modgen v Annexe: Modgen et l environnement Visual Studio

216 projet. Si vous avez déjà copié le répertoire de votre modèle, vous pouvez choisir de ne pas faire de copie de sauvegarde à cette étape. Cliquez «Next». L assistant vous demandera maintenant de confirmer que vous voulez convertir à Visual Studio Annexe: Modgen et l environnement Visual Studio 2008 Guide du concepteur de Modgen v10.1.0

217 Cliquez «Finish» pour convertir le projet de votre modèle. Une fois la conversion terminée, l assistant vous offrira de vous montrer le fichier de journalisation de la conversion. Guide du concepteur de Modgen v Annexe: Modgen et l environnement Visual Studio

218 Si vous choisissez de regarder ce fichier, attendez-vous à voir des avertissements. Lorsque la conversion est complétée, vous devriez voir le «Solution Explorer» dans le panneau de gauche. 210 Annexe: Modgen et l environnement Visual Studio 2008 Guide du concepteur de Modgen v10.1.0

219 Si vous ne le voyez pas, choisissez «Solution explorer» du menu «View». Toutes les propriétés de votre projet seront préservées lorsque vous convertirez à Visual Studio 2008 de Visual Studio 2005 de sorte que vous n aurez pas besoin d en modifier. Toutefous, si vous souhaitez quand même les modifier, cliquez à droite sur le projet dans le «Solution explorer» et choisissez «Properties». Vous devriez voir l écran suivant : Guide du concepteur de Modgen v Annexe: Modgen et l environnement Visual Studio

220 Pour voir les propriétés communes à toutes les configurations, choisissez «All Configurations» dans la liste combinée déroulante «configuration». Notez que lorsque vous changez la configuration choisie dans la liste combinée déroulante, si vous avez fait des modifications aux propriétés du projet, vous devriez voir le message suivant : Si vous désirez conserver les changements que vous avez faits, cliquez sur «Yes» pour continuer et changer de configuration. 212 Annexe: Modgen et l environnement Visual Studio 2008 Guide du concepteur de Modgen v10.1.0

221 Barre d outils Modgen 10 dans Visual Studio 2008 Lors de la première ouverture de Visual Studio 2008 après l'installation de Modgen 10, une barre d'outils sera créée pour Modgen 10 : De gauche à droite, ces commandes sont les suivantes : Tourner Modgen 10 : exécute Modgen 10 dans le répertoire de la solution. Cette commande est l'équivalent de l'outil qui devrait être créé dans les versions précédentes de Modgen 10. Le texte de sortie sera affiché en français. S'il n'y a pas de solution active dans Visual Studio 2008, le message suivant sera affiché : Guide du concepteur de Modgen 10 : ouvre le guide du concepteur de Modgen 10, en français. Le guide sera automatiquement fermé lors de la fermeture de Visual Studio Notes de publication de Modgen 10 : ouvre les notes de publication de Modgen 10, en français. Les notes de publication seront fermées lors de la fermeture de Visual Studio Documentation du modèle : ouvre la documentation du modèle en français. Cette commande suppose que le nom de la solution est également le nom du modèle. Par exemple, si la solution «Simpex.sln» est ouverte, cette commande suppose que le nom du modèle est «Simpex». Si votre solution n'a pas le même nom que le modèle, cette commande ne réussira pas à ouvrir la documentation. S'il n'y a pas de solution active, le message suivant est affiché : Cette commande vérifie que la documentation ( 2_FR.chm) existe et qu'elle est valide. Si la documentation n'est pas trouvée, la commande cherche le fichier 2.chm qui serait créé dans un modèle sans langue déclarée. Guide du concepteur de Modgen v Annexe: Modgen et l environnement Visual Studio

222 Si aucune documentation n'est trouvée, alors la commande demandera au concepteur s'il souhaite la générer : Une fois la documentation générée, la commande cherchera de nouveau pour le fichier de documentation (2_FR.chm or 2.chm) et, si elle le trouve, considérera que la documentation est valide et peut être affichée. Veuillez noter que dans un modèle avec des langues déclarées ne contenant pas «FR», la commande ne réussira pas à identifier la documentation à afficher. Même si un concepteur accepte de générer la documentation, les fichiers créés ne correspondront pas aux fichiers recherchés par la commande. Si la documentation est trouvée (soit 2_FR.chm ou 2.chm) mais est plus ancienne que l'exécutable, alors la commande offrira au concepteur de la re-générer avant de l'ouvrir : Avec cette option aussi, lorsque le modèle aura générer les fichiers d'aide, la commande cherchera de nouveau pour trouver soit le fichier 2_FR.chm soit le fichier 2.chm et, s'il existe, elle considérera que la documentation est valide et peut être affichée. À la fin de ces tests, s'il y a une documentation valide, la commande ouvrira le fichier de documentation du nom 1_FR.chm de préférence et, s'il n'existe pas, alors elle ouvrira le fichier 2_FR.chm. Veuillez noter que pour générer la documentation, la commande démarre le modèle avec l'option «-help». Cela signifie que l'exécutable est requis pour que cela puisse fonctionner. Si la documentation n'est pas trouvée et que l'exécutable (.exe) n'est pas trouvé non plus, le message suivant sera affiché : 214 Annexe: Modgen et l environnement Visual Studio 2008 Guide du concepteur de Modgen v10.1.0

223 Ouvrir BioBrowser 4 : démarre l application BioBrowser sans toutefois y ouvrir un fichier. Cette commande est disponible seulement si BioBrowser ou une version plus récente de cette application est installée sur la machine. Dans le cas contraire, la commande est désactivée. Changer la langue à l anglais : change la langue de toutes les autres commandes. Cette commande modifie les étiquettes des autres commandes à leur version anglaise et change également le comportement des autres commandes. Après que le concepteur ait cliqué sur cette commande, toutes les autres commandes seront exécutées en anglais. Cela signifie que le texte de sortie de Modgen 10 sera affiché en anglais et que les guides et notes de publication seront ouverts en anglais. La langue utilisée est préservée de sorte que lors de la prochaine utilisation de Visual Studio 2008, les commandes seront affichées dans la dernière langue utilisée. «Add New Item» : démarre le dialogue pour ajouter un nouvel item au projet. Ceci est l'équivalent de choisir la commande «Add New Item» soit en naviguant le menu «Project» soit en cliquant à droite sur le projet dans le «Solution Explorer». S'il n'y a pas de projet actif, la commande est désactivée. Lorsque l assistant démarre, le dialogue suivant apparaît : Guide du concepteur de Modgen v Annexe: Modgen et l environnement Visual Studio

224 Précisez le nom du nouveau module (par défaut «NomModuleName1»). Veuillez noter que les noms de modules de modèles Modgen 10 ne peuvent pas contenir d'espaces ou de caractères spéciaux et l'assistant refusera de créer un module dont le nom n'est pas un nom de module valide. Ne changez pas l'endroit de création («location»). Cliquez deux fois sur le gabarit («Template») intitulé «Modgen 10 - Module». L'assistant un fichier vide avec extension «mpp» et le fichier correspondant avec extension «cpp» et les ajoutera à votre projet. Chaque commande peut également être trouvée dans les menus de Visual Studio Les commandes «Tourner Modgen 10», «Ouvrir BioBrowser 4» et «Changer la langue de Modgen 10 à l anglais» se trouvent dans le menu «Tools» : Les commandes «Guide du concepteur de Modgen 10», «Notes de publication de Modgen 10» et «Documentation du 216 Annexe: Modgen et l environnement Visual Studio 2008 Guide du concepteur de Modgen v10.1.0

225 modèle» se trouvent dans le menu «Help» : Élaboration de modèles Modgen en C++ Ouvrez le fichier de projet.sln en Visual Studio Naviguez à cette fin vers le fichier.sln à l'aide d'explorer et cliquez deux fois sur le fichier. Assurez-vous que la configuration par défaut est la version «Release» et non pas la version de déboguage. Pour changer un paramètre de modèle et exécuter le modèle, cliquez deux fois sur le fichier.dat approprié dans les fichiers de projet. Vous ouvrez ainsi une fenêtre d'édition affichant le contenu du fichier paramétrique sélectionné. Modifiez le fichier au besoin à l'aide du programme d'édition Visual Studio Après avoir changé les valeurs paramétriques, vous pouvez exécuter le modèle en choisissant «Start Without Debugging» du menu «Debug». Pour modifier le code source du modèle et créer un modèle, ouvrez le fichier source.mpp désiré en cliquant deux fois sur son nom. Au menu «Tools», choisissez la commande «Tourner Modgen 10» de la barre d outils décrite à la section «Configuration de Visual Studio 2008 pour les application de Modgen». Examinez la sortie dans la fenêtre de sortie ou dans le fichier de sortie de Modgen («ModgenLog.htm») pour déceler les erreurs qui auraient pu s'y glisser. S il y a des erreurs, vous pouvez cliquer deux fois sur l erreur dans la fenêtre de sortie pour aller directement à l endroit du code où l erreur est survenue. Voici un exemple de ce texte de sortie : Guide du concepteur de Modgen v Annexe: Modgen et l environnement Visual Studio