Utiliser des fonctions D-V définies par l’utilisateur

Pour que Visum puisse identifier un fichier pour une fonction D-V définie par l’utilisateur, celui-ci doit présenter une interface particulière. Il est capital que chaque fichier *.dll exporte les fonctions listées pour que Visum puisse appeler correctement ce fichier *.dll pendant l’affectation.

Préparer un fichier *.dll pour une fonction D-V définie par l’utilisateur

Avec Visum il existe un fichier header UserDefinedVDF.h, que vous pouvez utiliser directement pour implémenter les fonctions requises en C++. Le fichier header et un projet exemple complet pour Microsoft Visual Studio figurent dans le dossier ...\Programmes\PTV Vision\PTV Visum 2021\Data\UserDefVDF. En principe, vous pouvez utiliser n’importe quel langage de programmation du moment qu’il permet de générer un fichier dll Windows comportant une interface conformément aux déclarations de fonctions de C++.

Les fonctions doivent présenter la même signature précise que dans UserDefinedVDF.h. Vous ne devez ni modifier la valeur de retour ni supprimer ou intervertir des paramètres.

Nota : La fonction D-V doit être continue et monotone croissante en ce qui concerne la charge. Ceci vaut pour toutes les valeurs possibles des paramètres.

Fonctions obligatoires dans le fichier *.dll

Déclaration	char Init ();
Description	Visum appelle cette fonction une première fois directement au démarrage et avant la première utilisation d’autres fonctions. Nota Utilisez la fonction pour initialiser vos propres structures de données ou pour exécuter d’autres fonctions de préparation le cas échéant.
Paramètres	aucun
Valeur de retour	true – initialisation effectuée avec succès false – échec de l’initialisation, il vaut mieux ne pas appeler le fichier *.dll

Déclaration	void Destroy ();
Description	Visum appelle cette fonction une première fois directement avant la fermeture et après le dernier appel des autres fonctions. Nota Utilisez la fonction pour des opérations de nettoyage le cas échéant, par exemple pour libérer de la mémoire allouée par allocation dynamique.
Paramètres	aucun
Valeur de retour	aucune

Déclaration	char IsThreadSafe();
Description	Visum appelle cette fonction une première fois directement au démarrage et avant le premier appel d’autres fonctions. La valeur de retour indique si les fonctions Calc... énumérées ci-après sont utilisables simultanément. La fonction peut alors être appelée une nouvelle fois avant la fin de l’appel précédent. Nota Visum peut se servir de ce parallélisme en cas d’implémentation multithread des procédures d’affectation.
Paramètres	aucun
Valeur de retour	true – utilisable simultanément false – non utilisable simultanément

Déclaration	char DependsOnTSys ();
Description	Visum appelle cette fonction une première fois directement au démarrage et avant le premier appel d’autres fonctions. Utilisez la fonction pour afficher si la fonction propre retourne des temps de parcours différents pour chaque système de transport ou si des charges par système de transport sont requises. Si ce n’est pas le cas, Visum n’a pas besoin d’extraire et de transférer ces charges aux fonctions Calc... et ne doit pas activer la fonction pour chaque système de transport, ce qui réduit le temps de calcul. Si la fonction est utilisée pour les connecteurs, la valeur 1 doit être retournée (voir Valeur de retour). La valeur 0 doit être retournée pour les (macro)mouvements au nœud et (macro)nœuds (voir Valeur de retour).
Paramètre	aucun
Valeur de retour	2 – requiert des charges par système de transport, mais retourne le même résultat pour tous les systèmes de transport 1 – requiert des charges par système de transport et retourne un résultat potentiellement différent pour les différents systèmes de transport 0 – utilise uniquement la charge totale dans UVP et fournit le même résultat pour tous les systèmes de transport

Déclaration	const wchar_t * GetName (const char * langid);
Description	Retourne un nom lisible pour la fonction, qui est inclus dans la liste de sélection des fonctions D-V.
Paramètres	langid est un code de langue qui peut être utilisé en option pour traduire le nom dans d’autres langues. Les valeurs suivantes sont actuellement possibles. ‘ENG’ – anglais ‘DEU’ – allemand ‘FRA’ – français ‘ITA’ – italien ‘POL’ – polonais ‘ESP’ – espagnol ‘CHI’ – chinois ‘JAP’ – japonais Nota Vous pouvez négliger la fonction lorsqu’elle n’est pas requise. Si vous utilisez le code de langue, nous recommandons de toujours traiter le cas d’un code inconnu, car d’autres langues peuvent être ajoutées à l’avenir sans information explicite.
Valeur de retour	Le nom lisible de la fonction en tant que chaîne de caractères UTF-8 codée sur 16 bits. La valeur doit être retournée au format UTF-8 pour intégrer les caractères spéciaux de certaines langues, notamment des langues asiatiques. Visum attend un pointeur vers une chaîne de caractères enregistrée dans le fichier *.dll. Nota La chaîne de caractères ne doit pas être allouée sur la pile pour que l’adresse reste valable après la fin de l’appel de la fonction.

Déclaration	const char * GetID ();
Description	Retourne normalement une chaîne de caractères utilisée comme ID sans équivoque pour la fonction. Cet ID est enregistré en interne dans le fichier version afin d’enregistrer l’assignation aux connecteurs ou aux types de tronçons, de nœuds ou de mouvements au nœud configurée par l’utilisateur, et en tant qu’ID de la fonction au format *.xml pour les paramètres de procédure.
Paramètres	aucun
Valeur de retour	Chaîne de caractères ID en tant que chaîne de caractères ASCII. La chaîne de caractères doit contenir uniquement les caractères 0..9, a..z, A..Z. Visum attend un pointeur vers une chaîne de caractères enregistrée dans le fichier *.dll. Nota La chaîne de caractères ne doit pas être allouée sur la pile pour que l’adresse reste valable après la fin de l’appel de la fonction.

Déclaration	int GetInterfaceVersion();
Description	La définition de l’interface pour les fichiers du type *.dll est versionnée afin de pouvoir modifier ou étendre les déclarations de fonctions ultérieurement. Retournez le numéro de version du fichier header pour lequel vous programmez vos fonctions. Visum compare la fonction retournée aux numéros de version connues du programme, appelle les fonctions dll en conséquence ou affiche un message d’erreur lorsque le numéro d’interface n’est pas pris en charge.
Paramètres	aucun
Valeur de retour	le numéro de version

Déclaration	void SetTsysInfo (int numtsys, const wchar_t * tsysids[])
Description	Visum appelle cette fonction à chaque fois que le nombre des systèmes de transport TI est modifié. Le nombre de systèmes de transport et un array avec les codes pour chaque système de transport sont retournés en tant que paramètre. Pour des raisons d’efficacité, Visum retourne le système de transport en tant qu’indice numérique aux fonctions Calc…, c.-à-d. en tant qu’indice basé sur 0 dans le champ tsysids. Nota Pour éviter des comparaisons de chaînes de caractères chères en temps de calcul dans ces fonctions souvent appelées, nous recommandons d’évaluer une fois l’indice numérique des systèmes de transport à traiter de manière particulière dans les fonctions D-V dans SetTsysInfo et de l’enregistrer.
Paramètres	numtsys – le nombre de systèmes de transport (= longueur du champ tsysids) tsysids – champ de chaînes de caractères UTF-8 codées sur 16 bits, chaque champ correspondant à la valeur de l’attribut Code pour un des systèmes de transport utilisés dans l’affectation.
Valeur de retour	non

Déclaration	double Calc (int tsysind, bool tsysisopen, int typ, int numlanes, double length, double cap, double v0, double t0, double gradient, double pcuvol, double vehvolsys[], int uval1, int uval2, int uval3, int uvaltsys, double para_a, double para_b, double para_c, double para_d, double para_f, double para_a2, double para_b2, double para_d2, double para_f2, double satcrit)
Description	L’implémentation de la fonction D-V elle-même. Visum appelle cette fonction pour calculer le temps de parcours actuel tChg pour chaque tronçon, mouvement au nœud, connecteur, nœud et un système de transport. Nota Vérifiez que la fonction est codée de manière efficace en ce qui concerne le temps de calcul, car elle est appelée très souvent.
Paramètres	Différents paramètres sont retournés pour les éléments de réseau. Nota Vous trouverez des détails dans la table ci-après.
Valeur de retour	tChg en [s]

En fonction du type d’élément de réseau, Visum retourne les paramètres suivants à la fonction Calc.

	Tronçon	Connecteur	Mouvement au nœud	Nœud
int tsysind	Indice du système de transport basé sur 0 (se rapportant au champ tsysids, retourné dans SetTsysInfo) pour lequel vous souhaitez calculer tChg
bool tsysisopen	Le réseau est-il autorisé au système de transport ?
int typ	0..99	0..9	0..9	0..99
int numlanes	NbVoies	1 (arbitraire)	1 (arbitraire)	1 (arbitraire)
double length	Longueur [longueur courte]	Longueur [longueur courte]	0 (arbitraire)	0 (arbitraire)
double cap	CapaTI [UVP]	10E10 ou CapaTI [UVP], lorsque les parts de connecteurs se rapportant au trafic émis/attiré total sont utilisées.	CapaTI [UVP]	CapaTI [UVP]
double v0	v0 [m/s]	Longueur/t0 (ou 0, lorsque t0=0)	0	0
double t0	Longueur/v0 [s] (ou 10E10, lorsque v0=0)	t0 [s]
double gradient	Pente	0 (arbitraire)	0 (arbitraire)	0 (arbitraire)
double pcuvol	ChgUVP en [UVP] en tant que combinaison linéaire de toutes les charges de SysTr en [véh] multipliées par la valeur de l’attribut UVP pour le système de transport. Nota Recommandé pour la plupart des applications.
double vehvolsys[]	Un array de toutes les charges de SysTr en [véh] pour les calculs d’UVP non standardisés. L’ordre des entrées correspond à l’ordre dans le champ tsysids, qui est retourné à SetTsysInfo.
double uval1/2/3	Les valeurs des attributs ValAdd1, ValAdd2 et ValAdd3
double uvaltsys	Valeur de l’attribut ValAdd-SysTr pour chaque système de transport	0
double para_a..f2	De la fenêtre Paramètres pour la fonction D-V
double satcrit	De la fenêtre Paramètres pour la fonction D-V (Sélectionner des fonctions D-V et configurer les paramètres)

Fonctions facultatives dans le fichier *.dll

Déclaration	double CalcDerivative (int tsysind, bool tsysisopen, int typ, int numlanes, double length, double cap, double v0, double t0, double gradient, double pcuvol, double vehvolsys[], int uval1, int uval2, int uval3, int uvaltsys, double para_a, double para_b, double para_c, double para_d, double para_f, double para_a2, double para_b2, double para_d2, double para_f2, double satcrit)
Description	Le programme appelle cette fonction pour calculer la dérivée du temps de parcours actuel tChg quant à l’occupation pour un système de transport donné et pour chaque tronçon, mouvement au nœud, connecteur, nœud. Cette fonction est appelée uniquement au sein des méthodes d’affectation selon les péages bicritères affectation à l’équilibre TRIBUT et méthode d’apprentissage TRIBUT. Nota Vérifiez que la fonction est codée de manière efficace en ce qui concerne le temps de calcul, car elle est appelée très souvent. Lorsque la fonction n’est pas implémentée dans le fichier *.dll, Visum calcule la dérivée de manière numérique, ce qui dure toutefois plus longtemps que de mettre à disposition CalcDerivative() dans le fichier *.dll.
Paramètres	comme pour Calc()
Valeur de retour	Dérivée de tChg en [s]

Déclaration	double CalcIntegral (int tsysind, bool tsysisopen, int typ, int numlanes, double length, double cap, double v0, double t0, double gradient, double pcuvol, double vehvolsys[], int uval1, int uval2, int uval3, int uvaltsys, double para_a, double para_b, double para_c, double para_d, double para_f, double para_a2, double para_b2, double para_d2, double para_f2, double satcrit)
Description	Le programme appelle cette fonction pour calculer l’intégrale du temps de parcours actuel tChg quant à l’occupation pour un système de transport donné et pour chaque tronçon, mouvement au nœud, connecteur, nœud. Nota Cette fonction n’est plus requise et il n’est donc pas nécessaire de l’implémenter. Lorsque la fonction n’est pas implémentée dans le fichier *.dll, Visum calcule l’intégrale de manière numérique, ce qui dure toutefois plus longtemps que de mettre à disposition CalcDerivative() dans le fichier *.dll.
Paramètres	comme pour Calc()
Valeur de retour	Intégrale de 0 à occupation de la fonction D-V en [s]

Interface alternative avec indication des attributs statiques dans la *.dll

La fonction Calc est activée avec un certain nombre d’attributs dépendant de l’élément de réseau comme le type, le nombre de voies, etc. mais ceci ne donne pas accès à d’autres attributs comme p. ex. des attributs définis par l’utilisateur. Il est possible d’implémenter trois autres fonctions facultatives dans la *.dll pour ce cas, qui permettent l’accès à des attributs numériques quelconques de l’élément de réseau. Ces attributs doivent être statiques au sein d’une affectation, c.-à-d. qu’ils ne doivent pas dépendre de la charge. L’accès à des attributs dépendant de la charge débouche sur des valeurs erronées. L’interface alternative est utilisée quand les trois fonctions suivantes sont implémentées. Les fonctions Calc(), CalcDerivative() et CalcIntegral() ne devraient pas être implémentées dans ce cas.

Déclaration	int GetNumStaticAttributes()
Description	Cette fonction retourne le nombre d’attributs statiques pour lesquels des valeurs sont transmises à CalculateWithStaticAttributes().
Paramètre	aucun
Valeur de retour	Nombre d’attributs statiques

 

Déclaration	const wchar_t * GetStaticAttributeID(int attributesIndexZeroBased)
Description	Doit fournir une chaîne qui contient un IDAttribut valide.
Paramètre	Index de l’attribut (0 à GetNumStaticAttributes()-1)
Valeur de retour	Chaîne IDAttribut en tant que chaîne de caractères ASCII. Visum attend un pointeur vers une chaîne de caractères enregistrée dans le fichier *.dll. Nota La chaîne de caractères ne doit pas être allouée sur la pile pour que l’adresse reste valable après la fin de l’appel de la fonction.

 

Déclaration	double CalculateWithStaticAttributes(int tsysind, char tsysisopen, double cap, double t0, pcuvol, double basevol, double vehvolsys[], double staticAttributeValues[], double para_a, double para_b, double para_c, double para_d, double para_f, double para_a2, double para_b2, double para_d2, double para_f2, double satcrit)
Description	L’implémentation de la fonction D-V elle-même. Visum appelle cette fonction pour calculer le temps de parcours actuel tChg pour chaque tronçon, mouvement au nœud, connecteur, nœud et un système de transport. Nota Vérifiez que la fonction est codée de manière efficace en ce qui concerne le temps de calcul, car elle est appelée très souvent.
Paramètres	Différents paramètres sont retournés pour les éléments de réseau. Les paramètres correspondent à ceux de la fonction Calc(), mais typ, numlanes, length, v0, uval1, uval2, uval3, uvaltsys font toutefois défaut. Un array des longueurs GetNumStaticAttributes() est transmis à la place dans staticAttributeValues avec les valeurs spécifiées par GetStaticAttributeID(). 0 est retourné si un attribut n’existe pas ou si l’attribut n’est pas numérique.
Valeur de retour	tChg en [s]

Exemple d’une fonction D-V définie par l’utilisateur

Deux systèmes de transport sont utilisés dans l’affectation, VP et PL.

• Pour le SysTr VP, la fonction D-V présente une forme linéaire, la pente changeant pour satcrit.

• Pour le SysTr PL, deux changements de pente pour d et e sont utilisés.

où

Les dérivées sont les suivantes :

Code source du fichier *.dll

#include “UserDefinedVDF.h”
#include “tchar.h”
int indHGV;  // index of the HGV tsys
wchar_t VDFName[] = _T(“ManualExample”); // UTF-8 !!
char  VDFID[] = “MANEX”;
int INTERFACE_VERSION = 1;
boolchar Init()
{
	indHGV = -1;
	return true;
}
void Destroy()
{
}
char DependsOnTSys()
{
  return 1;
}

const wchar_t* GetName(const char *langid)

{

	return VDFName;

}

const char* GetID(const char *langid)

{

	return VDFID;

}

int GetInterfaceVersion()

{

	return INTERFACE_VERSION;

}

void SetTsysInfo (int numtsys, const wchar_t * tsysids[])  

{

	for (int i = 0; i < numtsys; i++)

	{

		if (_tcscmp(tsysids[i], _T(“HGV”)) == 0) indHGV = i;

	}

}

double Calc (int tsysind, bool tsysisopen, int typ, int numlanes, double length, double cap, double v0, double t0, double gradient, double pcuvol, double vehvolsys[], int uval1, int uval2, int uval3, int uvaltsys, double para_a, double para_b, double para_c, double para_d, double para_f, double para_a2, double para_b2, double para_d2, double para_f2, double satcrit)

{ 

	double sat = pcuvol / cap;

	if (tsysind != indHGV) {

		if (sat < satcrit)

			return t0 * (1 + para_a * sat);

		else

			return t0 * (1 + para_a * satcrit + para_b * (sat-satcrit));

}

	else {

		if (sat < d)

			return t0 * (1 + para_a2 * sat);

		else {

		   if (d <= sat && sat < e)

			  return t0 * (1 + para_a2 * d + para_b2 * (sat-d));

		else

		    return t0 * (1 + para_a2 * d + para_b2*(e-d) + para_c*(sat-e));

		}

	}

}

double CalcDerivative (int tsysind, bool tsysisopen, int typ, int numlanes, double length, double cap, double v0, double t0, double gradient, double pcuvol, double vehvolsys[], int uval1, int uval2, int uval3, int uvaltsys, double para_a, double para_b, double para_c, double para_d, double para_f, double para_a2, double para_b2, double para_d2, double para_f2, double satcrit)

{ 

	double sat = pcuvol / cap;

	if (tsysind != indHGV) {

		if (sat < satcrit)

			return para_a;

		else

			return para_b;

	}

	else {

		if (sat < d)

			return para_a2;

		else {

			if (d <= sat && sat < e)

				return para_b2;

			else

				return para_c;

		}

	}

}

Exemple de fonction D-V définie par l’utilisateur avec des attributs statiques

Implémentation d’une fonction BPR pour montrer l’accès à des attributs statiques.

Code source du fichier *.dll

#include "UserDefinedVDF.h"

#include "tchar.h"

#include <math.h>

#include <float.h>

wchar_t VDFName[] = _T("ExampleStaticAttributes");

char  VDFID[] = "PTV_EXAMPLESTATICATTRIBUTES";

int INTERFACE_VERSION = 1;

char Init()

{

return true;

}

enum MyStaticIDs

{

V0PrT,

Length,

CapPrT,

TypeNo,

LastId

};

static const int MyMaxIDLength = 100;

static wchar_t staticAttributeIDs[LastId][MyMaxIDLength] =

{

L"V0PRT",

L"LENGTH",

L"CAPPRT",

L"TYPENO"

};

int GetNumStaticAttributes()

{

return LastId;

}

const wchar_t * GetStaticAttributeID(int attributesIndexZeroBased)

{

return staticAttributeIDs[attributesIndexZeroBased];

}

void Destroy()

{

}

char IsThreadSafe()

{

return true;

}

char DependsOnTSys()

{

return 0;

}

const wchar_t* GetName(const char *langid)

{

return VDFName;

}

const char* GetID()

{

return VDFID;

}

int GetInterfaceVersion()

{

return INTERFACE_VERSION;

}

void SetTsysInfo (int numtsys, const wchar_t * tsysids[])

{

}

double CalculateWithStaticAttributes(int tsysind, char tsysisopen, double cap, double t0,

double pcuvol, double basevol, double vehvolsys[],

double staticAttributeValues[],

double para_a, double para_b, double para_c, double para_d, double para_f,

double para_a2, double para_b2, double para_d2, double para_f2, double satcrit)

{

double const v0PrT = staticAttributeValues[V0PrT];

double const length = staticAttributeValues[Length];

double const mycap = staticAttributeValues[CapPrT];

double const typeNo = staticAttributeValues[TypeNo];

if (cap <= 0 || para_c <= 0 || v0PrT <= 0 || typeNo < 0) {

return DBL_MAX;

}

double sat = pcuvol / (cap * para_c);

double myt0 = 3.6 * length / v0PrT;

return myt0 * (1 + para_a * (pow(sat, para_b)));

}

Importer des fonctions D-V définies par l’utilisateur

1.  Compilez et liez le fichier *.dll avec l’environnement de développement souhaité.

2.  Nommez le fichier de bibliothèque selon la forme VisumVDF***.dll.

Nota : Vous pouvez remplacer *** par n’importe quelle chaîne de caractères respectant les conventions pour les noms de fichiers Windows. Vérifiez que les ID générés par la fonction GetID() sont sans équivoque. Lorsque plusieurs fichiers *.dll présente le même ID, seul le premier est chargé dans Visum. Tous les autres sont ignorés.

3.  Copiez le fichier dans le dossier ...\Utilisateurs\<utilisateur>\AppData\Roaming\PTV Vision\PTV Visum 2021\UserVDF-DLLs.

Nota : Ce dossier est créé par défaut lors de l’installation et parcouru au démarrage du programme. Vous pouvez aussi définir un autre dossier comme dossier par défaut pour vos fichiers *.dll créés. Le chemin d’accès correspondant doit être enregistré dans le fichier de dossiers de projets par défaut std.pfd à cet effet (Modifier l’emplacement d’enregistrement des fichiers). Cette modification n’est appliquée qu’après un redémarrage du programme.

Au démarrage, Visum recherche les fichiers *.dll et charge leurs contenus. Seuls les fichiers dont l’édition Windows (32 ou 64 bits) correspond à l’édition de Visum utilisée sont chargés. Les fonctions D-V définies par l’utilisateur sont alors disponibles au même titre que les fonctions D-V prédéfinies dans la fenêtre Paramètres pour la fonction D-V.

Nota : Après le démarrage du programme, Visum ne recherche plus de nouveaux fichiers *.dll. Si vous ajoutez une nouvelle fonction D-V définie par l’utilisateur, vous devez de nouveau redémarrer Visum. Si vous enregistrez un fichier *.bmp avec le même nom que le fichier *.dll dans le même dossier, l’image de la fonction D-V sélectionnée est affichée dans la fenêtre Paramètres pour la fonction D-V.

Créer des fonctions débit-vitesse définies par l’utilisateur avec VisualStudio C++

Vous trouverez un environnement pour Visual Studio 2019 à titre d’exemple dans le sous-dossier Data\UserDefVDF du dossier d’installation de Visum.

Nota : Avant l’utilisation, nous recommandons de copier le contenu de Data\UserDefVDF dans un dossier propre hors de C:\Program Files, car ce dossier peut être écrasé lors d’une mise à jour de Visum.

Tant la configuration du débogueur que de mise à jour créent des fichiers *.dll qui sont compatibles avec Visum. La variante de mise à jour est toutefois plus performante en termes de durée d’exécution.

• Démarrez Visual Studio 2019 puis ouvrez le fichier de solution UserDefVDF.sln.

Pour créer une *.dll propre, vous pouvez modifier soit l’un des projets existants, soit ajouter un nouveau projet à la solution.