Mainly modified setup.md to adapt to the new user_example_conf.m

The new user_example_conf.m is commited on 4/11/2020 09:46.

docs/source/nexuse_repo_instruction.md

@@ -19,6 +19,7 @@ We recommend to use a git GUI (e.g. GitKraken, Git Extensions, SourceTree, and [
 Why GitKraken:
 - It is stable in all operating systems (Linux, Mac, Windows)
 - It provides a good overview for the status of submodules, which is the key structure of our Nexus-e repo.
+- It has an embeded & very handy merging conflict resolution tool.
 - It is mature and well-documented.
 
 #### How do I get the repository?

docs/source/setup.md

@@ -59,7 +59,7 @@ DATABASE_PASSWORD
 ```
 
 - View the database
-  - Install MySQL and MySQL Workbench
+  - Install MySQL (Version 8.0 is recommended)  and MySQL Workbench
   - Connect to ETH VPN
   - Connect to the database with MySQL Workbench
     - Add a new MySQL connection
@@ -73,27 +73,6 @@ DATABASE_PASSWORD
     ```
     ![](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 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`.
-    - 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.
 
@@ -123,10 +102,14 @@ You could skip this section if you don't plan to run the whole Nexus-e platform
 - **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-).
-    - Gurobi paths  
+    - 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.
-        - Find out the path of `gurobi_setup.m`. Uncomment and adapt the variable `PATH_GUROBI_FOR_MATLAB` in `user_conf.m` accordingly.
 
 
 - **Python** (3.8.6 is recomended. Python 3.9 is not compatible with Gurobi 9.0.x yet.)
@@ -135,24 +118,48 @@ 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`.
-  - Python path: If you have more than one Python instances locally (e.g. if you use Mac or if have a python virtual environment), you need to configure Python path in Matlab. Otherwise, you could skip this step.
+  - 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.
-    - If you have a python virtual environment, you could configure it following the instructions in `user_conf.m`.
 
 - **GAMS** (32.2 is recomended)
   - 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_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.
+  - 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**.
 
+- **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)  
+    
 ##### 4. Run Nexus-e
 
 - Connect to ETH VPN (in order to connect with the database)
 - Open Matlab
+- Double check the `user_conf.m` file: whether you have edited `DB_SUFFIX` to be your name initials; whether the paths of the software are correct.
 - 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.
 - Run the script `run_Nexuse.m` in the `Run_Nexuse` folder. Note, make sure you are into the `Run_Nexuse` folder before runing the `run_Nexuse.m` script.
@@ -297,7 +304,9 @@ But still, we need to explicitely load all the dependencies, including modules (
   ```
   pip install --user -r nexus-e/requirements.txt
   ```  
-
+  You might encounter software compatibility problems when running Nexus-e on Euler, follow the link for possible solutions:
+  [Matlab & Python compatibility error: "ImportError: ...pyexpat...: undefined symbol: XML_SetHashSalt"](faq.html#matlab-python)
+  
 ##### 5. Run Nexus-e
 - cd to the `Run_Nexuse` folder
 - Before running `run_Nexuse.m` for the first time, you need to run `bench_Nexuse.m`.