Gurobi/fr

Gurobi est une suite logicielle commerciale qui permet de résoudre des problèmes complexes d'optimisation. Nous abordons ici son utilisation pour la recherche sur nos grappes.

Limites de la licence

Nous dispensons le soutien technique pour la licence gratuite disponible sur Graham, Cedar, Béluga et Niagara. Cette licence permet 4096 utilisations simultanées (avec jetons) et l'optimisation distribuée sur un maximum de 100 nœuds. Un utilisateur peut faire exécuter plusieurs tâches en simultané. Vous devez cependant accepter certaines conditions. Faites parvenir un courriel au soutien technique avec l'entente (Academic Usage Agreement) dûment complétée; vous pourrez ensuite utiliser les applications après un délai de quelques jours.

Academic Usage Agreement

My Alliance username is "_______" and I am a member of the academic institution "_____________________". This message confirms that I will only use the Gurobi license provided on Digital Research Alliance of Canada systems for the purpose of non-commercial research project(s) to be published in publicly available article(s).

Configurer votre compte

Il n'est pas nécessaire de créer le fichier ~/.licenses/gurobi.lic. Les paramètres pour l'utilisation de notre licence Gurobi sont configurés par défaut quand un module Gurobi est chargé sur une grappe. Pour savoir si votre nom d'utilisateur a été ajouté à la licence et qu'elle fonctionne correctement, lancez la commande qui suit.

$ module load gurobi
$ gurobi_cl 1> /dev/null && echo Success || echo Fail

Si vous obtenez Success, vous pouvez utiliser Gurobi immédiatement. Si vous obtenez Fail, vérifiez s'il existe un fichier nommé ~/.license/gurobi; si c'est le cas, supprimez ou renommez ce fichier, chargez le module Gurobi de nouveau et refaites le test.
Si vous obtenez encore Fail, vérifiez si une variable d'environnement définit GUROBI dans vos fichiers ~/.bashrc or ~/.bash_profile; si c'est le cas, supprimez la ou les lignes correspondantes ou mettez-les en commentaire, déconnectez-vous et connectez-vous de nouveau, chargez le module Gurobi de nouveau et refaites le test.
Si vous obtenez toujours Fail, contactez le soutien technique pour de l'assistance.

Utiliser un minimum de licences

Les licences peuvent être obtenues d’un seul serveur situé en Ontario; il est donc important de limiter les demandes autant que possible. Plutôt que d’obtenir une licence chaque fois que votre tâche requiert Gurobi, ce qui peut être des centaines, voire même des milliers de fois, faites en sorte que votre code fonctionne avec une seule licence pour toute la durée de la tâche, et ce, peu importe l’environnement que vous utilisez. Vous y gagnerez en performance puisque le temps de communication avec un serveur à distance est très long et de plus, notre serveur sera plus accessible aux autres utilisateurs de Gurobi. Si votre code n’est pas adapté en conséquence, le serveur pourrait ne pas pouvoir émettre de licence de façon intermittente; si ceci se produit, nous vous demanderons de mettre fin à toutes vos tâches et de corriger votre programme. Voyez comment créer un environnement pour tous vos modèles avec vos programmes en C++ ou en Python. Le même problème peut aussi survenir avec d’autres programmes qui fonctionnent en parallèle comme R, surtout quand plusieurs tâches simultanées sont soumises à l'ordonnanceur,

Allocations interactives

Ligne de commande

[gra-login2:~] salloc --time=1:00:0 --cpus-per-task=8 --mem=1G --account=def-xyz
[gra800:~] module load gurobi
[gra800:~] gurobi_cl Record=1 Threads=8 Method=2 ResultFile=p0033.sol LogFile=p0033.log $GUROBI_HOME/examples/data/p0033.mps
[gra800:~] gurobi_cl --help

Interpréteur interactif

[gra-login2:~] salloc --time=1:00:0 --cpus-per-task=8 --mem=1G --account=def-xyz
[gra800:~] module load gurobi
[gra800:~] echo "Record 1" > gurobi.env    see *
[gra800:~] gurobi.sh
gurobi> m = read('/cvmfs/restricted.computecanada.ca/easybuild/software/2017/Core/gurobi/8.1.1/examples/data/glass4.mps') 
gurobi> m.Params.Threads = 8               see **
gurobi> m.Params.Method = 2
gurobi> m.Params.ResultFile = "glass4.sol"
gurobi> m.Params.LogFile = "glass4.log"
gurobi> m.optimize()
gurobi> m.write('glass4.lp')
gurobi> m.status                           see ***
gurobi> m.runtime                          see ****
gurobi> help()

où

   * https://www.gurobi.com/documentation/8.1/refman/recording_api_calls.html
  ** https://www.gurobi.com/documentation/8.1/refman/parameter_descriptions.html
 *** https://www.gurobi.com/documentation/8.1/refman/optimization_status_codes.html
**** https://www.gurobi.com/documentation/8.1/refman/attributes.html

Répéter des appels API

Il est possible d'enregistrer des appels API et de rejouer l'enregistrement avec

[gra800:~] gurobi_cl recording000.grbr

Référence : https://www.gurobi.com/documentation/8.1/refman/recording_api_calls.html

Soumettre une tâche en lots sur une grappe

Une fois que votre script Slurm est prêt, vous pouvez le soumettre à la queue avec la commande sbatch script-name.sh. Vous pouvez vérifier l'état de vos tâches dans la queue avec la commande sq. Les scripts suivants solutionnent deux problèmes qui se trouvent dans le répertoire examples de chaque module Gurobi.

Exemple de données

Le script Slurm suivant utilise l' interface ligne de commande pour résoudre un modèle simple pour produire des pièces de monnaie écrit en format LP. La dernière ligne montre comment des paramètres peuvent être passés directement à l'outil ligne de commande gurobi_cl avec des arguments simples. Pour sélectionner les meilleurs paramètres pour un problème particulier et pour choisir les valeurs optimales, voyez les sections Performance and Parameters et Algorithms and Search dans la page Knowledge Base et dans la documentation Gurobi.

File : script-lp_coins.sh

#!/bin/bash
#SBATCH --account=def-group   # some account
#SBATCH --time=0-00:30        # specify time limit (D-HH:MM)
#SBATCH --cpus-per-task=8     # specify number threads
#SBATCH --mem=4G              # specify total memory
#SBATCH --nodes=1             # do not change

#module load StdEnv/2016      # for versions < 9.0.3 
module load StdEnv/2020       # for versions > 9.0.2

module load gurobi/9.5.0

rm -f coins.sol
gurobi_cl Threads=$SLURM_CPUS_ON_NODE Method=2 ResultFile=coins.sol ${GUROBI_HOME}/examples/data/coins.lp

Exemple avec Python

Le script Slurm suivant solutionne un modèle simple de l'emplacement de divers sites avec Gurobi Python. L'exemple montre comment paramétrer les fils en nombre égal à celui des coeurs alloués à la tâche en générant un fichier gurobi.env dans le répertoire de travail quand vous utilisez l'interface Gurobi Python. Ceci doit être fait pour chaque tâche soumise, autrement Gurobi lancera par défaut autant de fils d'exécution qu'il y a de cœurs physiques dans le nœud de calcul plutôt que d'utiliser le nombre de cœurs physiques alloués à la tâche par l'ordonnanceur, ce qui risque de ralentir la tâche et nuire aux tâches exécutées sur le même nœud par les autres utilisateurs.

File : script-facility.sh

#!/bin/bash
#SBATCH --account=def-group   # indiquez le nom du compte
#SBATCH --time=0-00:30        # indiquez la limite de temps (jj-hh:mm)
#SBATCH --cpus-per-task=4     # indiquez le nombre de fils
#SBATCH --mem=4G              # demandez toute la mémoire
#SBATCH --nodes=1             # ne pas modifier

#module load StdEnv/2020      # versions < 10.0.3
module load StdEnv/2023       # versions > 10.0.3

module load gurobi/11.0.1

echo "Threads ${SLURM_CPUS_ON_NODE:-1}" > gurobi.env

gurobi.sh ${GUROBI_HOME}/examples/python/facility.py

Environnements virtuels Python

Gurobi a sa propre version de Python qui ne contient aucun autre paquet de tiers autre que Gurobi. Pour utiliser Gurobi avec d'autres paquets Python comme NumPy, Matplotlib, Pandas et autres, il faut créer un environnement virtuel Python dans lequel seront installés gurobipy et par exemple pandas.
Avant de commencer, il faut décider quelle combinaison des versions Gurobi et Python nous voulons utiliser. La liste suivante montre les versions de Python supportées par les versions principales de Gurobi dans les environnements standards (StdEnv).

[name@server ~] module load StdEnv/2016; module load gurobi/8.1.1; cd $EBROOTGUROBI/lib; ls -d python*
python2.7  python2.7_utf16  python2.7_utf32  python3.5_utf32  python3.6_utf32  python3.7_utf32
 
[name@server ~] module load StdEnv/2020; module load gurobi/9.5.2; cd $EBROOTGUROBI/lib; ls -d python*
python2.7_utf16  python2.7_utf32  python3.10_utf32  python3.7  python3.7_utf32  python3.8_utf32  python3.9_utf32

[name@server ~] module load StdEnv/2023; module load gurobi/10.0.3; cd $EBROOTGUROBI/lib; ls -d python*
python3.10_utf32  python3.11_utf32  python3.7  python3.7_utf32  python3.8_utf32  python3.9_utf32

[name@server ~] module load StdEnv/2023; module load gurobi/11.0.1; cd $EBROOTGUROBI/lib; ls -d python*
python3.11

Installer Gurobi pour Python

As mentioned near the end of this official document How-do-I-install-Gurobi-for-Python, the previously recommended method for installing Gurobi for Python with setup.py has been deprecated to only be usable with Gurobi 10 versions (and older). Therefore, a new section has been added below which shows how to simultaneously download a compatible binary wheel from pypi.org and convert it into a format usable with the newly recommended command to install Gurobi for Python with Gurobi 11 versions (and newer).

Versions Gurobi 10.0.3 et moins récentes

Il faut suivre les étapes suivantes une fois sur chaque système avec StdEnv2023 et moins récents. Chargez d'abord les modules pour créer l'environnement virtuel, puis activez cet environnement.

[name@server ~] $ module load gurobi/10.0.3 python
[name@server ~] $ virtualenv --no-download  ~/env_gurobi
[name@server ~] $ source ~/env_gurobi/bin/activate

Installez les paquets que vous voulez utiliser, ici pandas. Par exemple

(env_gurobi) [name@server ~] $ pip install --no-index  pandas

Installez maintenant gurobipy dans l'environnement. À partir de StdEnv/2023, il n'est plus possible de l'installer dans $EBROOTGUROBI avec la commande python setup.py build --build-base /tmp/${USER} install, ce qui causerait une erreur fatale et le message error: could not create 'gurobipy.egg-info': Read-only file system. Copiez les fichiers ailleurs (par exemple dans /tmp/$USER) où l'installation sera faite, comme ci-dessous :

Instead the required files need to copied to elsewhere (such as /tmp/$USER) and installed from there, for example:

(env_gurobi) [name@server ~] $ mkdir /tmp/$USER
(env_gurobi) [name@server ~] $ cp -r $EBROOTGUROBI/{lib,setup.py} /tmp/$USER
(env_gurobi) [name@server ~] $ cd /tmp/$USER
(env_gurobi) [name@server ~] $ python setup.py install
(env_gurobi) [roberpj@gra-login1:/tmp/roberpj] python setup.py install
/home/roberpj/env_gurobi/lib/python3.11/site-packages/setuptools/_core_metadata.py:158: SetuptoolsDeprecationWarning: Invalid config.
!!

        ********************************************************************************
        newlines are not allowed in `summary` and will break in the future
        ********************************************************************************

!!
  write_field('Summary', single_line(summary))
removing /tmp/roberpj/build
(env_gurobi) [roberpj@gra-login1:/tmp/roberpj]
(env_gurobi) [name@server ~] $ deactivate
[name@server ~]

Versions Gurobi 11.0.0 (et plus récentes)

Once again, the following steps need to be done once per system and are usable with StdEnv/2023 and older. First load the modules to create the virtual environment and activate it. Version 11.0.0 is skipped since it has been observed to seg fault in at least one example versus Version 11.0.1 which runs smoothly.

[name@server ~] $ module load gurobi/11.0.1 python
[name@server ~] $ virtualenv --no-download  ~/env_gurobi
[name@server ~] $ source ~/env_gurobi/bin/activate

As before, install any needed Python packages. Since the following matrix example requires numpy, we install the pandas package:

(env_gurobi) [name@server ~] $ pip install --no-index  pandas

Next install gurobipy into the environment. As mentioned above and in [article] the use of setup.py to install Gurobi for python is deprecated starting with Gurobi 11. Both pip and conda are given as alternatives; however, since conda should not be used on alliance systems, the pip approach will be demonstrated here. The installation of gurobipy is slightly complicated since our Linux systems are set up with gentoo prefix. As a result neither A) the recommended command to download and install the gurobipy extension from the public PyPI server pip install gurobipy==11.0.1 mentioned in the article line or B) the offline command to install the wheel with python -m pip install --find-links <wheel-dir> --no-index gurobipy, will work. Instead a script available from the alliance maybe utilized to download and simultaneously convert the existing wheel into a usable format with a new name. There is one caveat, for each new Gurobi version the researcher must go into https://pypi.org/project/gurobipy/11.0.1/#history and click on the desired version followed by the Download files button located in the menu on the left. Finally, click to copy the https link for the wheel file (named gurobipy-11.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl in the case of Gurobi 11.0.1) and paste it as the --url argument as shown below :

(env_gurobi) [name@server ~] $ wget https://raw.githubusercontent.com/ComputeCanada/wheels_builder/main/unmanylinuxize.sh
(env_gurobi) [name@server ~] $ chmod u+rx unmanylinuxize.sh
(env_gurobi) [name@server ~] $ ./unmanylinuxize.sh --package gurobipy --version 11.0.1 --url 
https://files.pythonhosted.org/packages/1c/96/4c800e7cda4a1688d101a279087646912cf432b0f61ff5c816f0bc8503e0/gurobipy-11.0.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
(env_gurobi) [name@server ~] $ ls
gurobipy-11.0.1-cp311-cp311-linux_x86_64.whl  unmanylinuxize.sh
(env_gurobi) [name@server ~] $ python -m pip install --find-links $PWD --no-index gurobipy
(env_gurobi) [name@server ~] $ deactivate
[name@server ~]

Travailler dans l'environnement avec Gurobi

Nous pouvons maintenant activer notre environnement Gurobi avec

[name@server ~] $ module load gurobi/11.0.1 scipy-stack
  source ~/env_gurobi/bin/activate
  (env_gurobi) [name@server ~]

Les scripts Python comme les exemples fournis avec le module gurobi peuvent alors être exécutés dans l'environnement virtuel avec Python.

(env_gurobi) [name@server ~] $ python $EBROOTGUROBI/examples/python/matrix1.py

Les scripts Python peuvent maintenant importer Pandas et Gurobi.

[name@server ~] $ cat my_gurobi_script.py
  import pandas as pd
  import numpy as np
  import gurobipy as gurobi
  from gurobipy import *
  etc

Soumettez le script dans la queue avec sbatch my_slurm_script.sh.

File : my_slurm_script.sh

#!/bin/bash
#SBATCH --account=def-somegrp  # indiques le nom du compte
#SBATCH --time=0-00:30         # indiquez la limite de temps (jj-hh:mm)
#SBATCH --nodes=1              # utiliser un (1) nœud
#SBATCH --cpus-per-task=4      # indiquez le nombre de CPU
#SBATCH --mem=4000M            # demandez toute la mémoire

module load StdEnv/2023
module load gurobi/11.0.1
# module load scipy-stack      # uncomment if needed

echo "Threads ${SLURM_CPUS_ON_NODE:-1}" > gurobi.env

source ~/env_gurobi/bin/activate
python my_gurobi_script.py

Pour plus d'information sur la création et l'utilisation des environnements virtuels Python, voir Créer un environnement virtuel dans vos tâches.

Utiliser Gurobi avec Java

Vous devez aussi charger un module Java et ajouter une option à la commande Java pour permettre à l'environnement virtuel Java de localiser les bibliothèques Gurobi, comme dans l'exemple suivant :

File : gurobi-java.sh

#!/bin/bash
#SBATCH --time=0-00:30        # time limit (D-HH:MM)
#SBATCH --cpus-per-task=1     # number of CPUs (threads) to use	
#SBATCH --mem=4096M           # memory per CPU (in MB)

module load java/14.0.2
module load gurobi/9.1.2

java -Djava.library.path=$EBROOTGUROBI/lib -Xmx4g -jar my_java_file.jar

== Utiliser Gurobi avec des notebooks Jupyter ==

Vous trouverez de l'information sur Resources, Code and Modeling Examples et Optimization with Python – Jupyter Notebook Modeling Examples. Sur le site support.gurobi.com faites une recherche avec Jupyter Notebooks.

Voir aussi cette démonstration, à 38min 28sec de la vidéo.

Comment citer Gurobi

Voir How do I cite Gurobi software for an academic publication?