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

Commit 26be7dda authored by Xuqian Yan's avatar Xuqian Yan
Browse files

Added a section for user_conf.m

parent 811cbcb1
......@@ -8,7 +8,7 @@ Before setting up, ask for permission from <nexus-e@ethz.ch> to access the codes
```
#### 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.
Even though the current Nexus-e platform is **not** yet 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**.
......@@ -60,103 +60,109 @@ DATABASE_PASSWORD
```
![](images/mysql-workbench-dump.png)
##### 3. Prepare software & license
You could skip this section if you don't plan to run the whole Nexus-e platform locally.
- **Matlab** (R2018a or higher, Matlab R2020b is recomended)
- Set up database connector
- Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/). **Unzip** the file.
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)
- 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```.
##### 3. Prepare software & license
Apart from MySQL introduced above, we also need the following software to run Nexus-e locally. This will be introduced in this section. You could skip this section if you don't plan to run the whole Nexus-e platform locally.
- Matlab
- Python
- Gurobi
- GAMS
- Latex
- ImageMagick
- Create a **javaclasspath.txt** file in the **Matlab preferences folder**.
###### Matlab
- Download Matlab (R2018a or higher; R2020b is recomended). Available at [ETH IT shop](https://itshop.ethz.ch/EndUser/Items/Home).
- In the **javaclasspath.txt** file, write the path to the connector .jar file that you just copied.
E.g., On a Windows computer the path is similar to `C:\Users\user\AppData\Roaming\MathWorks\MATLAB\R2018a\mysql-connector-java-8.0.18\mysql-connector-java-8.0.18.jar`.
- Set up database connector
- Reload Matlab
- Download the **MySQL connector** from [here](https://dev.mysql.com/downloads/connector/j/). **Unzip** the file.
- 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)
```
- 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```.
- **Gurobi** (9.0 is recomended)
- Download Gurobi and set up a free Gurobi academic license <https://www.gurobi.com/academia/academic-program-and-licenses>.
- Connect Gurobi with Python following [this instruction](https://support.gurobi.com/hc/en-us/articles/360044290292-How-do-I-install-Gurobi-for-Python-).
- Save Gurobi path for Matlab
- Find out the path of `gurobi_setup.m`. (E.g., for mac, it is similar to `/Library/gurobi903/mac64/matlab`.)
- Open Matlab; under the tab "Home", click **Set Path**; select **Add Folder...**; browse to the folder containing `gurobi_setup.m` (from the step above); click **Open**.
- A new entry of the selected path will appear on the right side of the **Set Path** window; click **Save**.
![](images/matlab-setpath.png)
- Add Gurobi path for python in `user_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 the path of `gurobi.sh`. Uncomment and adapt the variable `PATH_GUROBI_FOR_PYTHON` in `user_conf.m` accordingly.
- Create a **javaclasspath.txt** file in the **Matlab preferences folder**.
- In the **javaclasspath.txt** file, write the path to the connector .jar file that you just copied.
E.g., On a Windows computer the path is similar to `C:\Users\user\AppData\Roaming\MathWorks\MATLAB\R2018a\mysql-connector-java-8.0.18\mysql-connector-java-8.0.18.jar`.
- **Python** (3.8.6 is recomended. Python 3.9 is not compatible with Gurobi 9.0.x yet.)
```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 identify potential issues for the transfer.
- 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)
```
- Python packages: install the required packages listed in `requirements.txt`.
- Add Python path in `user_conf.m`: If you have multiple Python instances locally (e.g. if you use Mac, if you have python virtual environments, or if you have multiple python versions), you need to configure Python path as instructed here. Otherwise, it might also work if you skip this. But to be safe, it is recommended to follow this step.
- 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 python path with which you connected Gurobi. Uncomment and adapt the variable `PATH_PYTHON` in `user_conf.m` accordingly.
- **GAMS** (32.2 is recomended. Our current license doesn't support versions newer than 32.)
- 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).
- Save GAMS path for Matlab
- Find out your GAMS path. It varies largely depending on your PC's operating system and the version of GAMS. For example, GAMS 32 on Mac has the path: `/Library/Frameworks/GAMS.framework/Versions/32/Resources`.
- Similar to how you configured Gurobi for Matlab: Open Matlab; under the tab "Home", click **Set Path**; select **Add Folder...**; browse to the folder containing `gurobi_setup.m` (from the step above); click **Open**.
- A new entry of the selected path will appear on the right side of the **Set Path** window; click **Save**.
- Connect GAMS with Python
- Follow the instruction [here](https://github.com/NREL/gdx-pandas).
- **MySQL**
So far you should have already downloaded MySQL from the section [Connect with the input database](#connect-with-the-input-database). Here we edit the MySQL-related info in the `user_conf.m` file.
- 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.)
- Edit the variable `DB_SUFFIX` in to be your name initials.
- Uncomment and adate the variable `PATH_MYSQL` to be the path of your MySQL installation.
- (Optional) Run Nexus-e with a local copy of the database
- Create a new text file to substitute `UserDBInfo.txt`.
For example, if you have dumped the remote database to your local hosted database with IP address `127.0.0.1`, you could create a new text file as the following:
```
127.0.0.1
3306
YOUR_LOCAL_USERNAME (e.g. "root")
YOUR_LOCAL_PASSWORD
```
- 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`).
- Place the new file in the same folder as `UserDBInfo.txt`.
- 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)
- **ImageMagick**
- Instructions for Windows:
- Download ImageMagick from [here](https://imagemagick.org/script/download.php#windows). Install ImageMagick from the .exe file. Tick all boxes when asked which packages to be installed (by default only the first three are selected).
- Additionally, download dependable software "Ghostscript" from [here](https://www.ghostscript.com/download/gsdnld.html). Select Public License Ghostscript. Install the Ghostscript.
- Optional (if ImageMagick does not work), download and install Visual studio from [here](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads).
- Instructions for Mac:
- Install ImageMagick from [here](https://imagemagick.org/script/download.php#macosx)
- Test if ImageMagick works:
- Open Windows command prompt and brows to folder that contains a pdf file, e.g., testch.pdf
- Use the following command to convert file: convert testch.pdf testch.jpg
###### Python
- Download [Python](https://www.python.org/downloads/). Version 3.8.6 is recomended. Python 3.9 is not compatible with Gurobi 9.0.x yet.
- (Optional) If you (will) use Python for multiple projects, it is recommended to create a virtual environment for Nexus-e (for example, using [virtualenv](https://uoa-eresearch.github.io/eresearch-cookbook/recipe/2014/11/26/python-virtual-env/)).
- Install the required python packages listed in `requirements.txt` (e.g., with command `pip install -r requirements.txt`).
###### Gurobi
- Download Gurobi (9.0 is recomended) and set up a free Gurobi academic license from [here](https://www.gurobi.com/academia/academic-program-and-licenses).
- Connect Gurobi with Python following [this instruction](https://support.gurobi.com/hc/en-us/articles/360044290292-How-do-I-install-Gurobi-for-Python-).
- Save Gurobi path for Matlab
- Find out the path of `gurobi_setup.m`. (E.g., for mac, it is similar to `/Library/gurobi903/mac64/matlab`.)
- Open Matlab; under the tab "Home", click **Set Path**; select **Add Folder...**; browse to the folder containing `gurobi_setup.m` (from the step above); click **Open**.
- A new entry of the selected path will appear on the right side of the **Set Path** window; click **Save**.
![](images/matlab-setpath.png)
###### GAMS
- Download [GAMS](https://www.gams.com/download/). Version 32.2 is recomended. Our current license doesn't support versions newer than 32.
- 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).
- Save GAMS path for Matlab
- Find out your GAMS path. It varies largely depending on your PC's operating system and the version of GAMS. For example, GAMS 32 on Mac has the path: `/Library/Frameworks/GAMS.framework/Versions/32/Resources`.
- Similar to how you configured Gurobi for Matlab: Open Matlab; under the tab "Home", click **Set Path**; select **Add Folder...**; browse to the folder containing `gurobi_setup.m` (from the step above); click **Open**.
- A new entry of the selected path will appear on the right side of the **Set Path** window; click **Save**.
- Connect GAMS with Python
- Follow the instruction [here](https://github.com/NREL/gdx-pandas).
###### Latex
- Download [Latex](https://www.latex-project.org/).
###### ImageMagick
- Instructions for Windows:
- Download ImageMagick from [here](https://imagemagick.org/script/download.php#windows). Install ImageMagick from the .exe file. Tick all boxes when asked which packages to be installed (by default only the first three are selected).
- Additionally, download dependable software "Ghostscript" from [here](https://www.ghostscript.com/download/gsdnld.html). Select Public License Ghostscript. Install the Ghostscript.
- Optional (if ImageMagick does not work), download and install Visual studio from [here](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads).
- Instructions for Mac:
- Install ImageMagick from [here](https://imagemagick.org/script/download.php#macosx)
- Test if ImageMagick works:
- Open Windows command prompt and brows to folder that contains a pdf file, e.g., testch.pdf
- Use the following command to convert file: convert testch.pdf testch.jpg
##### 4. Edit user_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.)
- In `user_conf.m` uncomment and modify the following variables based on your local computer's settings. More instructions can be found in `user_conf.m`.
- PATH_MYSQL
- PATH_PYTHON
- PATH_GUROBI_FOR_PYTHON (i.e., the path of `gurobi.sh`.)
- PATH_LATEX
- PATH_CONVERT
- PATH_GAMS
- (Optional) If you want to run Nexus-e with a [local copy of the database](#optional-make-a-local-copy-of-the-database)
- Create a new text file similar to `UserDBInfo.txt`. For example, if you have dumped the remote database to your local hosted database with IP address `127.0.0.1`, you could create a new text file as the following:
```
127.0.0.1
3306
YOUR_LOCAL_USERNAME (e.g. "root")
YOUR_LOCAL_PASSWORD
```
- Name the new file as `UserDBInfo_xxx.txt` (e.g., `UserDBInfo_local.txt`). Note: An underscore "_" after "UserDBInfo" is needed to not synchronize it on git (see the file `.gitignore`).
- Place the new file in the same folder as `UserDBInfo.txt`.
- 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';`).
##### 4. Run Nexus-e
##### 5. Run Nexus-e
- Connect to ETH VPN (in order to connect with the database)
- Open Matlab
......
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