Commit d93e954e authored by Xuqian Yan's avatar Xuqian Yan
Browse files

Added major contents for "Euler setup"

parent cefe1590
### **Setup** ### **Setup**
- [Get permissions](#get-permissions)
- [Local setup](#local-setup)
- [Get the codes](#get-the-codes)
- [Connect with the input database](#connect-with-the-input-database)
- [Prepare software & license](#prepare-software-license)
- [Run Nexus-e](#run-nexus-e)
- [Euler setup](#euler-setup)
#### Get permissions #### Get permissions
Before setting up, you need permissions to access the codes and the input database. Email the following people to ask for the corresponding permissions. Before setting up, you need permissions to access the codes and the input database. Email the following people to ask for the corresponding permissions.
...@@ -33,6 +25,7 @@ Before setting up, you need permissions to access the codes and the input databa ...@@ -33,6 +25,7 @@ Before setting up, you need permissions to access the codes and the input databa
- permission for the overarching **Nexus-e** repository (<https://gitlab.ethz.ch/xyan/nexus-e.git>) - permission for the overarching **Nexus-e** repository (<https://gitlab.ethz.ch/xyan/nexus-e.git>)
#### Local setup #### Local setup
Even though the current Nexus-e platform is **not** suitable to run locally because of high consumption of resources such as memory, we do recommend to at least get the codes and connect to the database locally in order to view, understand, and edit them easily.
Most the instructions below have been tested both on **Windows** and on **Mac**. Most the instructions below have been tested both on **Windows** and on **Mac**.
...@@ -86,20 +79,21 @@ An example can be found in `Shared/connectionInfoPSL.txt`. ...@@ -86,20 +79,21 @@ An example can be found in `Shared/connectionInfoPSL.txt`.
##### 3. Prepare software & license ##### 3. Prepare software & license
You could skip this section if you don't plan to run the whole Nexus-e platform locally.
- **Matlab** (2018a or higher) - **Matlab** (2018a or higher)
- Set up database connector - Set up database connector
- Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/). - Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/).
Or, if you have access to the Nexus-e polybox, use the `mysql-connector-java-8.0.18.zip` provided in the folder `02_Model/02_Model_Setup_Instruction`(**Unzip** the file before the next step). Or, if you have access to the Nexus-e polybox, use the `mysql-connector-java-8.0.18.zip` provided in the folder `02_Model/02_Model_Setup_Instruction` (**Unzip** the file before the next step).
- Copy the MySQL connector folder (e.g. mysql-connector-java-8.0.18) into a folder at your preference. - Copy the MySQL connector folder (e.g. mysql-connector-java-8.0.18) into a folder at your preference.
We recommend to put it into the **Matlab preferences folder**, which you can find by typing in Matlab Command Window ```prefdir```. We recommend to put it into the **Matlab preferences folder**, which you can find by typing in Matlab Command Window ```prefdir```.
- Create a **javaclasspath.txt** file in the **Matlab preferences folder**. - Create a **javaclasspath.txt** file in the **Matlab preferences folder**.
- In the **javaclasspath.txt** file, put the path to the connector .jar file. - In the **javaclasspath.txt** file, write the path to the connector .jar file that you just copied.
E.g., On Blazhe's Windows computer the path is `C:\Users\gblazhe\AppData\Roaming\MathWorks\MATLAB\R2018a\mysql-connector-java-8.0.18\mysql-connector-java-8.0.18.jar`. E.g., On Blazhe's Windows computer the path is `C:\Users\gblazhe\AppData\Roaming\MathWorks\MATLAB\R2018a\mysql-connector-java-8.0.18\mysql-connector-java-8.0.18.jar`.
- Reload Matlab - Reload Matlab
...@@ -116,7 +110,7 @@ An example can be found in `Shared/connectionInfoPSL.txt`. ...@@ -116,7 +110,7 @@ An example can be found in `Shared/connectionInfoPSL.txt`.
``` ```
- Python packages: install the required packages listed in `requirements.txt`. - Python packages: install the required packages listed in `requirements.txt`.
- Gurobi (9.x): get a free Gurobi academic license <https://www.gurobi.com/academia/academic-program-and-licenses> - Gurobi (9.x): Download gurobi and set up a free Gurobi academic license <https://www.gurobi.com/academia/academic-program-and-licenses>
- Python path: If you use Mac or if you want to run Nexus-e in a python virtual environment, you need to configure Python path in Matlab. Otherwise, you could skip this step. - Python path: If you use Mac or if you want to run Nexus-e in a python virtual environment, you need to configure Python path in Matlab. Otherwise, you could skip this step.
- Make a copy of `user_path_example_conf.m` in the folder `Run_Nexuse`. Name the copy as `user_path_conf.m`. (Note: You should only work with the local copy, because the original `xxx_example_conf.m` will be synchronized to git and it shouldn't be changed.) - Make a copy of `user_path_example_conf.m` in the folder `Run_Nexuse`. Name the copy as `user_path_conf.m`. (Note: You should only work with the local copy, because the original `xxx_example_conf.m` will be synchronized to git and it shouldn't be changed.)
- Find out your python path (it varies largely depending on your PC's operating system and how you installed python). Uncomment and adapt the variable `PATH_PYTHON` in `user_path_conf.m` accordingly. - Find out your python path (it varies largely depending on your PC's operating system and how you installed python). Uncomment and adapt the variable `PATH_PYTHON` in `user_path_conf.m` accordingly.
...@@ -141,11 +135,98 @@ An example can be found in `Shared/connectionInfoPSL.txt`. ...@@ -141,11 +135,98 @@ An example can be found in `Shared/connectionInfoPSL.txt`.
- Consult Blazhe Gjorgiev (gblazhe@ethz.ch) if you want to run other scripts in the `Run_Nexuse` folder. - Consult Blazhe Gjorgiev (gblazhe@ethz.ch) if you want to run other scripts in the `Run_Nexuse` folder.
#### Euler setup #### Euler setup
##### 1. Join the usergroup In order to run the full Nexus-e platform efficiently, we use [Euler](https://scicomp.ethz.ch/wiki/Euler), an ETH cluster for High Performance Computing. To set up the Nexus-e platform on Euler, you first need to access Euler. Instructions on accessing Euler and commands for Euler can be found [here](https://scicomp.ethz.ch/wiki/Getting_started_with_clusters#Euler).
##### 1. Join the Nexus-e user group
We have a user group for access to Nexus-e specific licenses (e.g. GAMS) and the Euler pre-paid share. The user group is called: **MAVT-esc-nexus-e**, and is set and maintained by D-MAVT IT. If you want to add new person to the user group, send e-mail to the servicedesk@mavt.ethz.ch.
To check whether you are added to the user group, use command line ssh to Euler (type `ssh username@euler.ethz.ch`), then type `groups` to show a list of groups that your user account is linked to, which should contain “MAVT-esc-nexus-e”.
##### 2. Get the codes ##### 2. Get the codes
##### 3. Prepare software & license
##### 4. Connect with the input database There are two ways to get codes to Euler: (1) use git and (2) copy from your local. Here we list the pros, cons, and use cases of both ways. You could decide which way to use.
- Comparison
- Git
- Pro: (1) Using git gaurantees that what you run on Euler is exactly the same as in the repository. (2) It is fast because only updated files will be reloaded by git and some files (e.g. results) are ignored by git.
- Con: (1) You need to run git commands in a terminal (no GUI). (2) You need to push your codes to the repository first and then pull it to Euler
- When to use: (1) When you want to test what is already in the repository, and (2) when you have made lots of changes to the codes and you might forget some files when you copy them to Euler manually.
- Copy from local
- Pro: (1) This can be done with a GUI tool. (2) You don't need to push to the repository first.
- Con: (1) Copying the whole Nexus-e folder takes time (a few minutes). (2) If you only copy selected files where you have made changes, you might by accident forget some.
- When to use: when you need to test small changes that you don't want to push to the repository yet.
##### 3. Connect with the input database
- Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/).
Or, if you have access to the Nexus-e polybox, use the `mysql-connector-java-8.0.18.zip` provided in the folder `02_Model/02_Model_Setup_Instruction` (**Unzip** the file before the next step).
- Copy the MySQL folder in the hidden .matlab folder (e.g., .matlab/2019b)
- Create a **javaclasspath.txt** file in the same folder as above.
- In the **javaclasspath.txt** file, write the path to the connector .jar file that you just copied.
E.g., On Blazhe's Euler account the path is `/cluster/home/gblazhe/.matlab/R2018a/mysql-connector-java-8.0.18/mysql-connector-java-8.0.18.jar`.
- Logoff and re-login to Euler
##### 4. Prepare dependencies
Unlike setting up Nexue-s locally, we don't need to download any software or license on Euler. Instead, they are all prepared for all users in the user group **MAVT-esc-nexus-e**. You should already be a member of the group if you have followed the [first step](#join-the-nexus-e-user-group).
But still, we need to explicitely load all the dependencies, including modules (an Euler term for "software") and python packages.
- Load modules
**Option 1**: Manually load modules every time before running Nexus-e
Copy the following commands into Euler:
```
module load new
module load gams/28.2
module load gurobi/8.1.1
module load matlab/R2018a
module load gcc/4.8.2
module load python/3.7.1
```
```eval_rst
|:warning:| Note: We used to load python/2.7.14. But we are now in the phase of transferring from python 2.x to python 3.x. Therefore, it is recommended to use python 3.x and identify potential issues for the transfer.
```
Your Euler window should look similar to this:
```eval_rst
.. image:: images/euler-module-load.png
:width: 300px
```
**Option 2**: Edit `.bash_profile` so that the modules are automatically loaded upon log in to Euler
Write the same commands at the end of `.bash_profile`. This is a hidden file in your Euler's home directory. After adding these commands, your `.bash_profile` should look similar to this:
![](images/euler-bash-profile.png)
**Test**: To test whether the modules have been successfully loaded, type `module list` in the commaand line. It should then list all loaded modules.
- Install python packages
This you only need to do it **once**, i.e. you don't need to do it everytime when you run Nexus-e.
In command line under your home directory, type
```
pip install --user -r nexus-e/requirements.txt
```
##### 5. Run Nexus-e ##### 5. Run Nexus-e
- cd to the `Run_Nexuse` folder
- Submit the job with a command such as
```
bsub -n 36 -R "model==XeonGold_6150" -R "rusage[mem=5180]" -W "10:00" matlab -r run_Nexuse
```
The parameters in this command can be costomized. Details can be found [here](https://scicomp.ethz.ch/wiki/Getting_started_with_clusters).
Here we give a short explanation to the example command above:
![](images/euler-job-submission.png)
After submission, Euler will respond by telling you what the jobID is.
##### 6. Useful commands on Euler
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment