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

Updated setup.md

parent 839318a9
docs/source/images/nexus-e-folder.png

96.2 KB | W: | H:

docs/source/images/nexus-e-folder.png

109 KB | W: | H:

docs/source/images/nexus-e-folder.png
docs/source/images/nexus-e-folder.png
docs/source/images/nexus-e-folder.png
docs/source/images/nexus-e-folder.png
  • 2-up
  • Swipe
  • Onion skin
......@@ -11,3 +11,4 @@ An integrated energy systems modelling platform | `nexus-e.org <http://nexus-e.o
euler_instruction.md
nexuse_repo_instruction.md
connect_new_module.md
faq.md
\ No newline at end of file
......@@ -13,7 +13,6 @@ Before setting up, you need permissions to access the codes and the input databa
- 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
......@@ -30,6 +29,7 @@ Even though the current Nexus-e platform is **not** suitable to run locally beca
Most the instructions below have been tested both on **Windows** and on **Mac**.
##### 1. Get the codes
Make sure you have installed [git](https://git-scm.com/).
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).
......@@ -41,26 +41,22 @@ The instructions here use **command lines**. If you have a GUI tool for git, you
```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.
You will be asked for your username and password for the repository and its submodules.
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.
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.
![](images/nexus-e-folder.png)
##### 2. Connect with the input database
- 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:
- 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):
```
itet-psl-s02
3306
YOUR_DATABASE_USERNAME
YOUR_DATABASE_PASSWORD
DATABASE_USERNAME
DATABASE_PASSWORD
```
An example can be found in `Shared/connectionInfoPSL.txt`.
- View the database
- Install MySQL and MySQL Workbench
......@@ -75,8 +71,27 @@ An example can be found in `Shared/connectionInfoPSL.txt`.
```eval_rst
|: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:
```
![](images/mysql-workbench-4.png)
![](images/mysql-workbench-dump.png)
- (Optional) Work with a local copy of the database
- 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 (e.g., named as `UserDBInfo_local.txt`) as the following:
```
127.0.0.1
3306
YOUR_LOCAL_USERNAME (e.g. "root")
YOUR_LOCAL_PASSWORD
```
- Place the new file in the same folder as `UserDBInfo.txt`.
- 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.)
- 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';`).
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)
(3) [Error: "The user specified as a definer ('xxx'@'%') does not exist ..."](faq.html#database-definer-missing)
##### 3. Prepare software & license
You could skip this section if you don't plan to run the whole Nexus-e platform locally.
......@@ -100,7 +115,7 @@ You could skip this section if you don't plan to run the whole Nexus-e platform
- 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");
conn = database("sys", YOUR_USERNAME, YOUR_PASSWORD, 'Vendor', 'MySQL', 'Server', "YOUR_HOST");
isopen(conn)
```
......@@ -112,9 +127,9 @@ You could skip this section if you don't plan to run the whole Nexus-e platform
- Python packages: install the required packages listed in `requirements.txt`.
- 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.
- 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`.
- 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`.
- **GAMS**
- Download from [here](https://www.gams.com/download/)
......@@ -122,8 +137,8 @@ You could skip this section if you don't plan to run the whole Nexus-e platform
- 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.
- 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.
##### 4. Run Nexus-e
......@@ -144,18 +159,14 @@ To check whether you are added to the user group, use command line ssh to Euler
##### 2. Get the codes
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.
- 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.
- 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.
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)
##### 3. Connect with the input database
- Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/).
......
Supports Markdown
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