To receive notifications about scheduled maintenance, please subscribe to the mailing-list gitlab-operations@sympa.ethz.ch. You can subscribe to the mailing-list at https://sympa.ethz.ch

setup.md 13.3 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
- Xuejiao Han (xuhan@eeh.ee.ethz.ch):
  - permission for the **DistIv** repository
12
  - access to the **PSL server** for the database (server name: itet-psl-s02)
13
- Jared Garrison (garrison@fen.ethz.ch):
14
15
  - permissions for the **eMark** repository
  - permissions for the **Shared** repository,
16
- Blazhe Gjorgiev (gblazhe@ethz.ch):
17
18
19
20
21
22
23
  - 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
24
  - permission for the overarching **Nexus-e** repository (<https://gitlab.ethz.ch/xyan/nexus-e.git>)
25

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

Xuqian Yan's avatar
Xuqian Yan committed
29
30
31
Most the instructions below have been tested both on **Windows** and on **Mac**.

#####  1. Get the codes
32
Make sure you have installed [git](https://git-scm.com/).
Xuqian Yan's avatar
Xuqian Yan committed
33

34
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 "GitKraken" can be found in section [Nexus-e repository instructions](nexuse_repo_instruction.html).
Xuqian Yan's avatar
Xuqian Yan committed
35
36
37
38
39
40
41
42
43

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

Xuqian Yan's avatar
Xuqian Yan committed
44
  You will be asked for your username and password for the repository and its submodules.
Xuqian Yan's avatar
Xuqian Yan committed
45

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, and 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

Xuqian Yan's avatar
Xuqian Yan committed
53
- Find information to connect with the database in `UserDBInfo.txt` in the repository. The file contains four lines (for confidentiality the username and password is not written here, but can be found in the file):
54
55
56
```
itet-psl-s02
3306
Xuqian Yan's avatar
Xuqian Yan committed
57
58
DATABASE_USERNAME
DATABASE_PASSWORD
59
60
61
62
63
64
```

- View the database
  - Install MySQL and MySQL Workbench
  - Connect to ETH VPN
  - Connect to the database with MySQL Workbench
65
    - Add a new MySQL connection
66
    ![](images/mysql-workbench-1.png)
67
    - Input connection information
68
    ![](images/mysql-workbench-2.png)
69
70
    - 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)
71
    ```eval_rst
72
73
    |: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:
    ```
Xuqian Yan's avatar
Xuqian Yan committed
74
    ![](images/mysql-workbench-dump.png)
75

76
77
- (Optional) Work with a local copy of the database

78
79
    - Create a new text file to substitute `UserDBInfo.txt`.  
    For example, if you have dumped the common database to your local hosted database with IP address `127.0.0.1`, you could create a new text file as the following:
Xuqian Yan's avatar
Xuqian Yan committed
80
81
82
83
84
    ```
    127.0.0.1
    3306
    YOUR_LOCAL_USERNAME (e.g. "root")
    YOUR_LOCAL_PASSWORD
85
86
    ```  
    - Name the new file as  `UserDBInfo_xxx.txt`  (e.g., `UserDBInfo_local.txt`). An underscore "_" after "UserDBInfo" is needed to not synchronize it on git (see the file `.gitignore`).
Xuqian Yan's avatar
Xuqian Yan committed
87
    - Place the new file in the same folder as `UserDBInfo.txt`.
88
89
    - Point to the new file in the script.
      - Make a copy of `user_example_conf.m` in the folder `Run_Nexuse`. Name the copy as `user_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.)
Xuqian Yan's avatar
Xuqian Yan committed
90
      - Uncomment and adapt the variable `DB_INFO_FILE` in `user_conf.m` to be the new file name (e.g., `DB_INFO_FILE = 'UserDBInfo_local.txt';`).
91
92
93
94

    You might encounter the following problems when you run Nexus-e with a local database, follow the link for possible solutions:
    (1) [Error: "Access denied for user 'your_username'@'your_host_address' ..."](faq.html#access-denied-to-access-database)
    (2) [Error: "The server time zone value 'xxx' is unrecognized ..."](faq.html#database-server-timezone-issue)
Xuqian Yan's avatar
Xuqian Yan committed
95
    (3) [Error: "The user specified as a definer ('xxx'@'%') does not exist ..."](faq.html#database-definer-missing)
Xuqian Yan's avatar
Xuqian Yan committed
96
97

##### 3. Prepare software & license
98
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
99

Xuqian Yan's avatar
Xuqian Yan committed
100
- **Matlab** (2018a or higher)
Xuqian Yan's avatar
Xuqian Yan committed
101
102
103

  - Set up database connector

104
    - Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/).
105
    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
106

107
    - Copy the MySQL connector folder (e.g. mysql-connector-java-8.0.18) into a folder at your preference.
Xuqian Yan's avatar
Xuqian Yan committed
108
109
110
111
    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**.

112
    - In the **javaclasspath.txt** file, write the path to the connector .jar file that you just copied.
Xuqian Yan's avatar
Xuqian Yan committed
113
114
115
    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
116
117

    - 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.
Xuqian Yan's avatar
Xuqian Yan committed
118
    ```
Xuqian Yan's avatar
Xuqian Yan committed
119
    conn = database("sys", YOUR_USERNAME, YOUR_PASSWORD, 'Vendor', 'MySQL', 'Server', "YOUR_HOST");
Xuqian Yan's avatar
Xuqian Yan committed
120
121
    isopen(conn)
    ```
122
123

- **Python** (3.x)
Xuqian Yan's avatar
Xuqian Yan committed
124
125
126
  ```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.

127
  ```
Xuqian Yan's avatar
Xuqian Yan committed
128
  - Python packages: install the required packages listed in `requirements.txt`.
129
  - Gurobi (9.x): Download gurobi and set up a free Gurobi academic license <https://www.gurobi.com/academia/academic-program-and-licenses>
130
  - 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.
Xuqian Yan's avatar
Xuqian Yan committed
131
132
133
    - Make a copy of `user_example_conf.m` in the folder `Run_Nexuse`. Name the copy as `user_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_conf.m` accordingly.
    - If you have a python virtual environment, you could configure it following the instructions in `user_conf.m`.
Xuqian Yan's avatar
Xuqian Yan committed
134
135
136
137
138
139
140

- **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
Xuqian Yan's avatar
Xuqian Yan committed
141
142
    - If you haven't done so, make a copy of `user_example_conf.m` in the folder `Run_Nexuse`. Name the copy as `user_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_conf.m` accordingly.
Xuqian Yan's avatar
Xuqian Yan committed
143
144
145


##### 4. Run Nexus-e
146

Xuqian Yan's avatar
Xuqian Yan committed
147
148
- Connect to ETH VPN (in order to connect with the database)
- Open Matlab
149
150
- Before running `run_Nexuse.m` for the first time, you need to run `bench_Nexuse.m`.
  It is recommended to repeat this step after major changes to the modules eMark and CentIv.
Xuqian Yan's avatar
Xuqian Yan committed
151
152
153
154
- 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.

155
#### Euler setup
156
157
158
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
159
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`.
160
161

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
162
163

##### 2. Get the codes
164

165
166
167
168
- 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```
Xuqian Yan's avatar
Xuqian Yan committed
169
  You will be asked for your username and password for the repository and its submodules.
170

Xuqian Yan's avatar
Xuqian Yan committed
171
172
In the end, the folder will look like the screenshot below. Note: tThe `Results` folder will be automatically generated when you run Nexus-e.
![](images/euler-nexus-e-folder.png)
173
174

##### 3. Connect with the input database
175
- Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/).
176
177
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).

178
- Copy the MySQL folder in the hidden .matlab folder (e.g., .matlab/2019b)
179
180
181

- Create a **javaclasspath.txt** file in the same folder as above.

182
- In the **javaclasspath.txt** file, write the path to the connector .jar file that you just copied.
183
184
185
186
187
188
189
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).

190
But still, we need to explicitely load all the dependencies, including modules (an Euler term for "software") and python packages.
191
192
193

- Load modules

194
  **Option 1**: Manually load modules every time before running Nexus-e
195

196
  Copy the following commands into Euler:
197
198
199
200
201
202
203
204
205
206
207
  ```
  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.
    ```
208
    Your Euler window should look similar to this:
209
210
211
    ```eval_rst
    .. image:: images/euler-module-load.png
      :width: 300px
212
    ```
213

214
  **Option 2**: Edit `.bash_profile` so that the modules are automatically loaded upon log in to Euler
215

216
  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:
217
218
219
  ![](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.
220

221
- Install python packages
222
223

  This you only need to do it **once**, i.e. you don't need to do it everytime when you run Nexus-e.
224
225
226
227
228
229

  In command line under your home directory, type
  ```
  pip install --user -r nexus-e/requirements.txt
  ```

Xuqian Yan's avatar
Xuqian Yan committed
230
##### 5. Run Nexus-e
231
232
233
234
235
- 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
```
236
The parameters in this command can be costomized. Details can be found [here](https://scicomp.ethz.ch/wiki/Getting_started_with_clusters).
237
238
239
240

Here we give a short explanation to the example command above:
![](images/euler-job-submission.png)

241
After submission, Euler will respond by telling you what the jobID is.