setup.md 12.8 KB
Newer Older
1
2
3
4
### **Setup**

#### Get permissions

5
6
Before setting up, you need permissions to access the codes and the input database. Email the following people to ask for the corresponding permissions.

Xuqian Yan's avatar
Xuqian Yan committed
7
```Note:: |:warning:| Currently, the codes are only accessible with an ETH account.
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
```

- Xuejiao Han (xuhan@eeh.ee.ethz.ch): 
  - permission for the **DistIv** repository 
  - access to the **PSL server** for the database (server name: itet-psl-s02)
- Jared Garrison (garrison@fen.ethz.ch): 
  - permissions for the **eMark** repository
  - permissions for the **Shared** repository,
  - username and password for the **database** 
- Blazhe Gjorgiev (gblazhe@ethz.ch): 
  - permission for the **Cascades** repository
  - permission for the **Run_Nexuse** repository
- Elena Raycheva (elena.raycheva@esc.ethz.ch):
  - permission for the **CentIv** repository
- Florian Landis  (landisf@ethz.ch):
  - permission for the **GemEl** repository
- Xuqian Yan (xuqian.yan@esc.ethz.ch):
Xuqian Yan's avatar
Xuqian Yan committed
25
  - permission for the overarching **Nexus-e** repository (<https://gitlab.ethz.ch/xyan/nexus-e.git>)
26

27
#### Local setup
28
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.
29

Xuqian Yan's avatar
Xuqian Yan committed
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
Most the instructions below have been tested both on **Windows** and on **Mac**.

#####  1. Get the codes

The instructions here use **command lines**. If you have a GUI tool for git, you could use the corresponding operations in the GUI tool instead. An example using a GUI tool "GitAhead" can be found in section [Nexus-e repository instructions](nexuse_repo_instruction.html).

- Create a folder where you want to put the codes

- cd to that folder

- Clone the overarching repository with this command:

  ```git clone --recursive https://gitlab.ethz.ch/xyan/nexus-e.git```

  You will be asked for your username and password for the repository and its submodules. Input your ETH username and password.

Xuqian Yan's avatar
Xuqian Yan committed
46
In the end, the folder will look like the screenshot below. Note: You might not see the hidden files whose names start with a dot; the `UserDBInfo.txt` file will be added in the sction [Connect with the input database](#connect-with-the-input-database); the `Results` folder will be automatically generated when you run Nexus-e.
Xuqian Yan's avatar
Xuqian Yan committed
47
48
49
50
51
52

![](images/nexus-e-folder.png)


##### 2. Connect with the input database

53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
- Get access to the database  
Follow the section [Get permissions](#get-permissions) to get access to the database server (PSL server: itet-psl-s02) and your username & password for the database.

- Create a `UserDBInfo.txt` file in the folder where you put the codes as shown in [Get the codes](#get-the-codes). The file should contain four lines:
```
itet-psl-s02
3306
YOUR_DATABASE_USERNAME
YOUR_DATABASE_PASSWORD
```
An example can be found in `Shared/connectionInfoPSL.txt`.

- View the database
  - Install MySQL and MySQL Workbench
  - Connect to ETH VPN
  - Connect to the database with MySQL Workbench
    - Add a new MySQL connection  
    ![](images/mysql-workbench-1.png)
    - Input connection information  
    ![](images/mysql-workbench-2.png)
    - Click the button `Test Connection`. You will be asked to input your database password. Then you will see a seccess message:  
    ![](images/mysql-workbench-3.png)  
    ```eval_rst
Xuqian Yan's avatar
Xuqian Yan committed
76
    |:warning:| By default, everyone has write permission to the database. Therefore, to be safe, always make a local copy of the database before playing with it - i.e., first “Dump” it to a local folder, then import it to your personal MySQL account. These can be done in this window:  
77
78
79
    ```  
    ![](images/mysql-workbench-4.png)

Xuqian Yan's avatar
Xuqian Yan committed
80
81

##### 3. Prepare software & license
82
You could skip this section if you don't plan to run the whole Nexus-e platform locally.
Xuqian Yan's avatar
Xuqian Yan committed
83

Xuqian Yan's avatar
Xuqian Yan committed
84
- **Matlab** (2018a or higher)
Xuqian Yan's avatar
Xuqian Yan committed
85
86
87
88

  - Set up database connector

    - Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/).  
89
    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).
Xuqian Yan's avatar
Xuqian Yan committed
90
91
92
93
94
95

    - 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```.

    - Create a **javaclasspath.txt** file in the **Matlab preferences folder**.

96
    - In the **javaclasspath.txt** file, write the path to the connector .jar file that you just copied.  
Xuqian Yan's avatar
Xuqian Yan committed
97
98
99
100
101
102
103
104
105
    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
    
    - Test whether a database connector is set up successfully. Write the following commands in Matlab (substitue `YOUR_USERNAME` and `YOUR_PASSWORD` with your credentials for the database). If the second command returns `1`, it means success.  
    ```
    conn = database("sys", YOUR_USERNAME, YOUR_PASSWORD, 'Vendor', 'MySQL', 'Server', "itet-psl-s02");
    isopen(conn)
    ```
Xuqian Yan's avatar
Xuqian Yan committed
106
107
108
109
110
111
112
  
- **Python** (3.x)  
  ```eval_rst
  |:warning:| Note: 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 locally and identify potential issues for the transfer.

  ```  
  - Python packages: install the required packages listed in `requirements.txt`.
113
  - Gurobi (9.x): Download gurobi and set up a free Gurobi academic license <https://www.gurobi.com/academia/academic-program-and-licenses>
Xuqian Yan's avatar
Xuqian Yan committed
114
115
116
117
118
119
120
121
122
123
124
125
126
  - 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.)
    - 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.
    - If you have a python virtual environment, you could configure it following the instructions in `user_path_conf.m`.

- **GAMS**
  - Download from [here](https://www.gams.com/download/)
  - Set GAMS License
    - Use the `gamslice.txt` provided in polybox `02_Model/02_Model_Setup_Instruction`.
    - Install the license: [here](https://support.gams.com/installation:how_do_i_install_a_license_file) or [here](https://www.youtube.com/watch?v=vSe3YGkUVoc) or (for MacOS) [here](https://www.gams.com/latest/docs/UG_MAC_INSTALL.html).
  - GAMS path
    - If you haven't done so, 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 GAMS path (it varies largely depending on your PC's operating system and the version of GAMS). Uncomment and adapt the variable `PATH_GAMS` in `user_path_conf.m` accordingly.
Xuqian Yan's avatar
Xuqian Yan committed
127
128
129


##### 4. Run Nexus-e
130

Xuqian Yan's avatar
Xuqian Yan committed
131
132
133
134
135
136
- Connect to ETH VPN (in order to connect with the database)
- Open Matlab
- Run the script `run_Nexuse.m` in the `Run_Nexuse` folder
  - You could change the variables `scen`, `tpRes`, and `limDifference` as instructed in the script
  - Consult Blazhe Gjorgiev (gblazhe@ethz.ch) if you want to run other scripts in the `Run_Nexuse` folder.

137
#### Euler setup
138
139
140
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
141
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. To join the user group, ask Blazhe Gjorgiev (gblazhe@ethz.ch) to send an email to `servicedesk@mavt.ethz.ch`.
142
143

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”.
Xuqian Yan's avatar
Xuqian Yan committed
144
145

##### 2. Get the codes
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215

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
  ```

Xuqian Yan's avatar
Xuqian Yan committed
216
##### 5. Run Nexus-e
217
218
219
220
221
222
223
224
225
226
227
228
229
- 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.