This document is obsolete please go to the new version.

ILLUMINA USER'S GUIDE

General information

In that document, the red text means that you have to adapt that part to your specific case.

Operating system

Illumina should be used with a computer running under linux with a fortran and gcc compilers installed (e.g. gfortran) and mercurial.

Other software dependancies

The following software are needed by the system

• make
• bash
• vim-common
• python-numpy
• python-pyproj
• python-matplotlib
  
• python-gdal
• gri
• bc
• imagemagick
• gnuplot
• mercurial

Installing the code

ILLUMINA model is available from bitbucket:

https://bitbucket.org/aubema/illumina

All sources codes are released under GNU public licence.

To install the model from google code, please follow these steps:

Then you must compile the code:

Then edit the $HOME/.bashrc file. This will render the executables accessible from anywere on the file system.

Preparing a modelling experiment

Step 1: making light inventory for each spectral line

We have to create zones files. In ILLUMINA, zone files allow the user to define different geographical zones with different type of lamp (different by their relative contribution to the DMSP-OLS satellite imagery, photometry function or light output pattern (LOP), lamp height). Two or more zones may be in the same geographical region or partly overimposed. Since each zone defines the lamp photometry, the user have to combine both lamp type LOP in an average LOP to define some kind of new combined lamp type. By default, as a first step, all the geographical domain will be defined by 2 zones (urban and contryside). These two cases are discriminated on the basis of a threshold value to the OLS relative radiance. Then additional zones are defined as circle shaped zones with center position and radius. Each new zone overwrite the precedings. To create zone you have to edit a .zon file with a simple text editor like kwrite or gedit following the format shown below:

Sample .zon file for a Hg spectral line

First line content

This line contain 3 elements:

1. total number of circular zones
2. percentage of DMSP-OLS luminance coming from the given element (here Hg) in urban regions
3. urban LOP file name

Second line

1. urban/rural DMSP-OLS luminance threshold (on OLS image the maximal value is 63, we estimated that 45 is a good threshold to capture cities)
2. percentage of DMSP-OLS luminance coming from the given element (here Hg) in rural regions
3. rural LOP file name

Following lines

1. x' central position of the circular zone. {#x'=x+1#} where x is determined with a wheel click on the pgm file with imagemagik (display)
2. y' central position of the circular zone. {#y'=Nby-y #} where y is determined with a wheel click on the pgm file with imagemagik (display) and Nby is the image height in pixel.
3. radius of the circular zone (pixel).
4. percentage of DMSP-OLS luminance coming from the given element (here Hg) in that zone
5. zone LOP file name

Step 2: find a DMS-OLS image in ILLUMINA's standard pgm format

Sample file for southern part of Quebec province

Step 3: Create a reflectance image in ILLUMINA's standard pgm format

We are using MODIS reflectance product for summer (~mid August) and winter (~mid February) at the nearest neighbourg wavelength according to the following table:

According that DMSP make a yearly average, we have to make a correction for the impact of snow cover during winter (if applicable). For Quebec's region we roughly estimated that there is snow cover 0.25 of the year so that we assumed that the yearly reflectance is given by:

{#0.75 x MODIS_R(summer) + 0.25 x MODIS_R(winter) #}

This file is created with moypondpgm16bit program.

Visual example with MODIS band 4 year 2009:

Step 4: find or create a land/water image in ILLUMINA's standard pgm format

This file is important to correct an important artefact arising from the fact that water surface are almost non reflecting and the optical resolution of DMSP-OLS (2.7km) is lower that the numerical resolution (1km) and then there is abnormal light overspill sometimes over water surface. In the following process, having a very low reflectivity with non zero OLS value will be interpreted as a very high light luminosity. To correct roughly for that we force lamp luminosity to be 0 over water. If you do not already have a water mask, you can use the following rules to create a new one. Ocean surface may be identified with a Digital elevation model by setting a threshold near 0m in elevation. Rivers or lakes can be identifies using a threshold on MODIS summer reflectance but this will need some validation or training with local geographical maps. If some water pixels are not captured by this dual filter, you will see some abnormally high luminosity in the luminosity files. Most of the time it will appear as white lines in cities because many cities are colocated with rivers.

Masque des plans d'eau du Québec

Step 5: run ols3lum program

Run program ols2lum with files created at steps 2, 3 et 4 as summarized below:

1. Output root name of the experiment: this name will be used to create the output luminosity files (_lumlp_NN.pgm) will be appended, with NN giving the zone number (01 is for urban and 02 for rural).
2. Fichier ols (format pgm illumina): file name of step 2
3. Fichier reflectance (format pgm illumina): file name of step 3
4. Fichier masque eau (format pgm illumina): file name of step 4
5. Fichier zone: file name of step 1

Step 6 : file quick verification

Open all the _lumlp_NN.pgm files to confirm that they are realistics according to the specific experiment. lumlp files are giving the light luminosity for each zone at the given wavelength.

Examples with 546 Hg line but contrast boosted

Zone 1 = cities	Zone 2 = countryside
Zone 3 = Sherbrooke	Zone 4 = 25 km around Obs. Mont-Mégantic
Zone 6 = Cookshire	Zone 7 = Lac Mégantic

Zone 5, wich is the Astrolab parking lot, have not been shown here because there is no Hg lamps. This image was consequently completely black.

Step 7: Preparation of the batch file

This file is a bash program that will generate a lot of running experiment according to the number of desired cases for each variable.

We must define the following variables in the makeBATCH program:

We must also define the following arrays in makeBATCH program:

• Note that the example given above was for summer case but the data should be define independently for each period.

Step 9

Il faut maintenant créer un répertoire pour chaque humidité analysée dans lequel deux sous-répertoire seront inclus, c'est-à-dire ete et hiver. Dans notre cas, nous avons créer trois répertoires, soit rh50, rh70 et rh80.

Maintenant, il faut amener dans ces répertoires tous les fichiers requis pour chaque saison, de même que le modèle ILLUMINA.

Étape 10

Afin d'exécuter les calculs, il faut maintenant se connecter à un Cluster. Dans notre cas, nous nous connectons à galileo.

Ensuite, il est nécessaire de recompiler le modèle ILLUMINA à l'aide de makeILLUMINA, soit grâce à la commande suivante:

bash makeILLUMINA

Les répertoires nécessaires, créés à l'étape 9 doivent maintenant être transférés sur galileo. Chacun de de ces répertoires doit contenir l'exécutable de ILLUMINA (illumina) compilé sur le cluster.

Étape 11

À présent, il faut créer le programme qui exécutera les calculs, de même que de nouveaux répertoires pour chaque saison ou période prise en compte.

bash makeBATCH Nom_fichier_batch

Notes:

• Nom_fichier_batch peut prendre n'importe quelle valeur. Si aucun nom n'est fourni alors makeBATCH choisira TortureMammouth par défaut.
• La commande qstat permet de vérifier l'état des Clusters(noeuds de calcul) avant ou pendant l'exécution.
• Pour effacer une tâche, utiliser la commande qdel suivie du numéro de la tâche à effacer.

Pour exécuter le calcul, il faut effectuer la commande suivante:

bash Nom_fichier_batch

Cette étape doit être répétée pour chaque saison et chaque valeur d'humidité relative.

Étape 12: extraire les résultats

Le modèle ILLUMINA génère deux fichiers image par calcul effectué, soit un fichier illustrant la contribution (PCL) et l'autre illustrant la sensibilité à la pollution lumineuse (PCW). Il produit aussi la valeur de radiance dans la direction calculée. Cette valeur n'est toutefois pas calibrée car les fichiers lumlp ne sont pas calibrés au départ.

Par exemple, les fichiers illustrant respectivement la contribution et la sensibilité à la pollution lumineuse pour l'expérience 2005 ont la forme suivante:

2005_pcl.pgm et 2005_pcw.pgm

Il est maintenant temps d'extraire les données et de renommer les fichiers obtenus puisque les noms attribués par Nom_fichier_batch n'indiquent pas toutes les valeurs requises pour que les fichiers soient correctement indexés sur le portail. Actuellement ces informations sont indiquées dans les noms du répertoire contenant les résultats.

Pour extraire les données, il faut se placer dans votre répertoire $HOME

cd $HOME

cp svn/illumina/trunk/extract-output-data.bash .

Les fichiers Nom_fichier_batch devraient s'y trouver. Ensuite y effectuer la commande suivante:

bash extract-output-data.bash experiment_name Nom_fichier_batch

• Notez qu'ici Nom_fichier_batch, pourrait être remplacé par un nom contenant plusieurs fichiers batch. Cela s'avère utile par exemple lorsque le nombre d'exécution est plus grand que 1000 et que le makeBATCH a divisé l'expérience en plusieurs fichiers batch (par ex.: megantic-2005-ete_1, megantic-2005-ete_2, megantic-2005-ete_3, etc). Alors il serait avantageux de faire la commande:

cat megantic-2005-ete_* > list-megantic-2005-ete

Dans cet exemple, la commande pour extraire les données serait:

bash extract-output-data.bash 2005 list-megantic-2005-ete

Ici 2005 est le nom de l'expérience (i.e. ce qui précède _436_lumlp (ou autre longueur d'onde que 436) dans les fichiers d'intrants) et list-megantic-2005-ete est le nom du fichier texte contenant tous les fichiers batch correspondant à l'été 2005 pour Mégantic.

A la fin de l'exécution de extract-output-data.bash, un répertoire Results/experiment_name aura été créé dans $HOME et il contiendra tous les fichiers PCL (ex.: PCL-x302y58-2005-ta0.05-wl436-el15-az0.pgm) et tous les fichiers PCW (ex.L PCW-x302y58-2005-ta0.05-wl436-el15-az0.pgm). Ce répertoire contiendra aussi un fichier data.txt contenant toutes les valeurs de radiances non calibrées et un fichier *.o* pour chaque run. Ces fichiers contiennent le log de l'execution.

Note: Dans les noms venant d'être cités en exemple, chaque terme correspond à un paramètre de l'environnement :

• PCL ou PCW = type de données
• x320y58 = position de l'observateur
• 2005 = nom de l'expérience
• ta0.05 = Épaisseur optique
• wl436 = Longueur d'onde
• el15 = Angle d'élévation
• az0 = Angle azimutal

Étape 13 Je pense que cette étape n'est pas nécessaire

Comme les cartes ont une incertitude de l'ordre de 3 km, il existe un programme capable d'étaler les points lumineux apparaissant sur les cartes afin que ceux-ci soient représentatif de l'incertitude. Ce programme est nommé interp-pgm16bit. Il entrer le nom des fichiers créés à l'étape 13, de même que la résolution souhaitée en pixel (Dans notre cas 1 pixel = 1 km). Par exemple, pour l'hiver avec une épaisseur optique de 0,1 et une longueur d'onde de 568 nm:

Étape 14

Il peut être plus facile d'analyser une carte lorsque celle-ci est en couleur. Pour ce faire, il faut d'abord savoir quel est la résolution numérique de l'image (8bit ou 16 bit) à l'aide de la commande suivante:

more ete_...*pgm

• Si le nombre indiqué est 255, la résolution est de 8 bit.
• Si le nombre indiqué est 65535, la résolution est de 16 bit.

Selon la résolution de l'image, on utilisera le programme pgm8bit2color.bash ou le programme pgm16bit2color.bash.

Donc, on entre le programme approprié suivi du nom du fichier à mettre en couleur. Par exemple:

pgm16bit2color.bash PCL-x302y58-2005-ta0.05-wl436-el15-az0.pgm

Étape 15: Renommage des fichiers pour le portail

Pour être bien indexés par le portail les fichiers doivent être nommés comme suit:

PCL-Astrolab_b_midnight_summer_2005-ta0.05-wl436-el15-az0.pgm

Signification: PCL = type de données Astrolab = nom du site d'observation b_midnight_summer_2005 = période (b_midnight est pour before midnight, période par défaut des données OLS) ta0.05 = épaisseur optique des aérosols de 0.05 wl436 = longueur d'onde de 436nm el15 = 15 deg d'angle d'élévation az0 = 0 deg d'angle d'azimuth

Exemple de commande pour renommer les fichiers ci-haut correctement:

list=`ls -1 *x302y58-2005*`;for i in ⚠ $list; do o=`echo $i |sed 's/x302y58-2005/Astrolab-b_midnight_summer_2005/g'`;mv ⚠ $i $o; done

Essentiellement cette commande changera x302y58-2005 pour Astrolab-b_midnight_summer_2005. I.e. avant le tiret, c'est le nom du site d'observation qui remplace la position et après on met la période de la nuit suivie de la saison et de l'année. Les tirets séparent les champs utilisés par le portail alors que les underscore servent à séparer les mots d'un champs donné. Par ex., le champ période contient 4 mots (b, midnight, summer, 2005). Notez que si la modélisation a été faite pour après minuit on utilisera les mots a et midnight (a_midnight) et si la modélisation correspond à l'hiver on utilisera le mot winter. Le nom du site est à la discrétion de l'utilisateur du présent guide mais devra ne pas porter à confusion pour les futurs usagers du portail.