• View
• Edit
• History
• Print

IlluminaLightGuide2022

ILLUMINA Light USER'S GUIDE

Hector Linarez Arroyo Ph.D., Alexandre Simoneau M.Sc. & Martin Aubé, Ph.D. copyright 2022

Latest update: August 23 2022

News

General informations

This users guide aim to help users of the ILLUMINA light sky radiance model to prepare and manage their own simulations. We hope that the document is accurate enough but will be happy to improve it according to some difficulties you may encounter when using it. For any help please contact the PI Dr Martin Aubé (martin.aube at cegepsherbrooke.qc.ca). This guide is exclusively for the simplified model Illumina Light, if you plan to use the full model please use the pertinent guide.

Description

Illumina Light is designed to be run in a personal computer or a laptop. It computes the artificial zenith sky brightness for the V band (more bands coming soon). Moreover, the natural light model Gambons (Masana et al 2021) is embedded in the pipeline. Combining both models the user will know the the total sky brightness similar to what it is obtained with measurements, as well as the separate contribution from the natural and artificial components.

The model presented also produces a contribution map. This result shows where the artificial light that is polluting the zenith over the location selected is originated, and to what extent.

Monthly averaged data from the VIIRS-DNB satellite sensor is used for inferring the radiance emitted by sources.

Installation

Operating system

ILLUMINA light should be used with a computer running under Linux with Fortran and gcc compilers (e.g. gfortran) and Python (3.8) with the pip versioning system installed. The easiest path to get into Illumina light is to use of a virtual environment to manage the Python libraries. For a debian based system you can do it that way.

(:source:) sudo apt-get install python3-venv python3 -m venv $HOME/illum (:sourceend:)

We assume here that the virtual environment will be in $HOME/illum. You can change that path to whatever you want but in the following steps we will assume you have done it that way.

Activate the virtual environment (:source:) source $HOME/illum/bin/activate (:sourceend:)

Other software dependencies

The following software are needed by the system

• git
• python
• gfortran
• python3-pip

We also suggest installing some Python libraries that are not needed but are useful.

• ipython
• gdal

In all cases, the most recent version of the code should be used. The code is evolving rapidly and then by updating your version frequently, you will benefit of new features and bug fixes.

Installing the code

The ILLUMINA project is available from github:

https://github.com/aubema/illumina

All sources codes are released under GNU public license.

To download the model from github, please follow these steps: (:source:) cd mkdir git cd git git clone https://github.com/aubema/illumina.git (:sourceend:)

Then you must compile the code: (:source:) cd $HOME/git/illumina bash ./bin/makeILLUMINA (:sourceend:)

Then modify the $HOME/.bashrc file by typing the following commands in the terminal window. This will make the programs executable from anywhere on the file system. (:source:) echo "PATH=\$PATH:\$HOME/.local/bin:\$HOME/git/illumina/bin" >> $HOME/.bashrc (:sourceend:)

Now you have installed the Illumina project, that includes the full model and Illumina Light. To use Illumina Light you need to change the branch of the project from master to GUI: (:source:) cd $HOME/git/illumina git checkout GUI git pull (:sourceend:)

You should receive the following message: (:source:) Switched to branch 'GUI' Your branch is up to date with 'origin/GUI' (:sourceend:)

Finally, the model is installed using: (:source:) pip3 install -e $HOME/git/illumina (:sourceend:)

Preparing an execution

In order to execute the model, some data manipulation is needed to prepare it for the model. It is strongly recommended to separate the data from the code by creating a new directory somewhere on your computer and placing all the relevant data within.

When it is done, enter this directory and execute illum init. The script will copy the necessary files to the current directory. The parameter files can then be modified to contain the correct values for your experiment.

Running the model

In order to start working with Illumina Light you only need one command: (:source:) illum light (:sourceend:)

The first time you run Illumina Light all the inputs files that are required will be downloaded automatically. It may take several minutes.

Then visual interface will open.

Visual interface

The user only has to deal with the different options that the visual interface offers. There is no need to use the terminal anymore.

1. Location

This section has 5 boxes to fill:

- Name: experiment name, any string is accepted. Designed for helping the user organize experiments.
- Latitude and longitude: coordinates of the location to study. Insert values in degrees only (FORMAT NOT ACCEPTED: DEGREE, MINUTES AND SECONDS).
- Date: the date will be used to select the correct satellite radiance data (month) and to compute the natural sky brightness (day and month). Year is not needed as the model only uses the data from 2019 (by now).
- Altitude: elevation from ground level in meters of the observation point.

2. Experiment

- Direction: Zenith (fixed).
- Band: Visual band of the Johnson system (fixed).
- Add natural light: if the user wants information about the natural sky brightness and consequently the total sky brightness should select this option. If the user is only interested in artificial brightness this option there is no need to select this option.

3. Atmosphere

The atmospheric definition has been defined following the OPAC model (Hess et al 1998).

- Aerosols: there are several options that the user can choose for defining the aerosol components of the atmosphere. They define the most typical cases. If the user wants to go further and define a specific case please use the full model and not Illumina Light.
- Humidity: relative humidity levels.
- Aod: aerosol optical depth (by clicking on std values, the model will fill automatically this value).
- Alpha: Angstrom coefficient (by clicking on std values, the model will fill automatically this value).
- Aerosol height: aerosol scale height that defines the vertical profile (by clicking on std values, the model will fill automatically this value).

4. Light sources

The user has to define here the light sources around the observation point. All the sources will be defined in the same manner, the user should define the mean values.

The user can introduce as many kinds of lamps as wanted:

- %: the percentage (or any kind of ratio) of the kind of lamps introduced. The program will normalize the proportion taking into account all the kind of lamps introduced.
- Technology: the user can choose between several options.
- ULOR: upward light output ratio, i.e. the percentage of light that is emitted over the horizon of the lamp.

The user has to click on "Add light fixture" for any combination of the options above. A message in the dialog box below should appear stating all the lamps added.

In case of error, click on "Clean All" and start over.

5. Architectural features around light sources

- Mean height of the lamps in meters.
- Mean street width in meters.
- Mean building height in meters.
In case that there are no obstacles around the light fixtures, que user should check the "No obstacles" option.

6. Define simulation

By clicking this button the experiment will be defined. It requires that all the previous steps have been completed.

When finished, a message will appear on the Dialog Box with a summary of the definition of the experiment.

7. Run simulation

By clicking this button the computation will start. The model will use as many CPUs as possible. It normally takes less than 7 minutes for 5 CPU intel i7 8th generation. The time needed changes from experiment to experiment depending on the sources and other variables.

Results

Results will appear in the dialog box. Units of the radiances are in mag/arcsec².

Additionally a contribution map will be displayed.

In the experiment folder the user will find and all-sky map of the natural light (Gambons).

8. Alternative scenarios

It is possible to compare the results obtained in the main experiment to what will happen if the light fixtures were changed. To do such comparisons the main experiment ought to represent the real scenario as the model adapts the radiance detected by the satellite VIIRS-DNB depending on the light fixtures installed.

The user has to define a new sets of lights: follow steps 4, 6 and 7.
Any messages related to this case and the final result will be showed in the dialog box of the right side.