README.md

# Download Forcing

## Prerequisites:
- Copernicus: you need to [create an account](https://data.marine.copernicus.eu/register?redirect=%2Fproducts)
- Naos: you must create a token in: edit profile > access token > add new token (nb: check all the boxes in “select scopes”). Copy the generated token somewhere, it will no longer be displayed


## Launch with https://lab.jumeaux-numeriques.fr

### Create a new kernel

#### Create a kernel with demo@demo.fr user

Connect to https://lab.jumeaux-numeriques.fr with user demo@demo.fr

Open a new terminal and execute the following command lines :

```
cd work/download-forcing/
source download-forcing-env/bin/activate
pip install -r requirements.txt
python -m ipykernel install --user --name=download-forcing-kernel
```

#### Create a kernel with your user

Connect to https://lab.jumeaux-numeriques.fr with your user

Open a new terminal and execute the following command lines :

```
conda install -c conda-forge ipywidgets
cd work
NAOS_TOKEN=your token
git clone https://$NAOS_TOKEN@forge.naos-cluster.tech/gpmb/modeles-telemac/download-forcing.git
cd download-forcing
python -m venv download-forcing-env
source download-forcing-env/bin/activate
pip install -r requirements.txt
python -m ipykernel install --user --name=download-forcing-kernel
```

### Select the kernel

click on "File Browser" :

<img src="documentation/jupyterlab-filebrowser.png" width="40%" />

Open download-forcing.notebook.ipynb

click on "Switch Kernel" :

<img src="documentation/jupyterlab-switch-kernel.png" width="40%"/>

Select download-forcing-kernel :

<img alt="alt text" src="documentation/jupyterlab-select-kernel.png" width="70%"/>

### Run the simulation



### Start execution

- In the first cell `Credentials` : 
    - Copy your NAOS token in `NAOS_TOKEN: str="my token" `. This token is used to get all the forked projects in NAOS, and to update them with the forcing files generated.
    - Set `WRITE_IN_NAOS` to `False` if you don't want to update the forked projects in NAOS (debug mode).

- Execute this cell: 
    - you need to enter your Copernicus user and password
    - this will generate the credentials to download the Copernicus datas, and save the credentials in : `home/.copernicusmarine/.copernicusmarine-credentials` 
    - Note : this identification must only be done once, it is no longer useful once the credentials have been generated and saved in your workspace

- Enter your parameters either :

  - in the interface part : "Execute with the interface"
       - Choose a study in all forked projects
       - Choose the start and end dates
       - Click on `Update forcing files`
    
  - or in the command line part : "Execute with a prompt"
       - By default, the forked projects used are :
           - 2D : https://forge.naos-cluster.tech/gpmb/modeles-telemac/fork-target/public-study-2D
           - 3D : https://forge.naos-cluster.tech/gpmb/modeles-telemac/fork-target/public-study-3D
       - Set all parameters (2D or/and 3D) 
       - Choose the start and end dates
       - Execute the cell

### Update the project with the latest version (only for new versions)

```
git init
git reset --hard HEAD
git pull https://$NAOS_TOKEN@forge.naos-cluster.tech/gpmb/modeles-telemac/download-forcing.git
```


## With Docker

You can execute the download-forcing.py script easily with the provided docker image:

```
docker run \
    -e COPERNICUS_LOGIN="your_username" \
    -e COPERNICUS_PASSWORD="your_password" \
    -e START_DATE="2024-05-01T00:00:00.000000Z"
    -e END_DATE="2024-05-04T00:00:00.000000Z"
    [...]
    forge.naos-cluster.tech:5050/gpmb/modeles-telemac/download-forcing:latest
```

## Sources 

### Copernicus Marine

- [Copernicus Marine Toolbar](https://help.marine.copernicus.eu/en/articles/7949409-copernicus-marine-toolbox-introduction)
- [Credentials configuration](https://help.marine.copernicus.eu/en/articles/8185007-copernicus-marine-toolbox-credentials-configuration)
- [Load a dataset](https://help.marine.copernicus.eu/en/articles/8287609-copernicus-marine-toolbox-api-open-a-dataset-or-read-a-dataframe-remotely)