Commit 0afb12b6 authored by Xuqian Yan's avatar Xuqian Yan
Browse files

Updated contents regarding repo migration

parent 1fadb42e
...@@ -25,8 +25,8 @@ from recommonmark.transform import AutoStructify ...@@ -25,8 +25,8 @@ from recommonmark.transform import AutoStructify
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------
project = 'Nexus-e' project = 'Nexus-e'
copyright = '2020, Xuqian Yan' copyright = '2021, Energy Science Center, ETH Zurich'
author = 'Xuqian Yan' author = 'Nexus-e'
# The full version, including alpha/beta/rc tags # The full version, including alpha/beta/rc tags
release = '0.0.1' release = '0.0.1'
......
### **Nexus-e repository instructions** ### **Repository instructions**
For a full instruction to work with git repository, please see [here](https://git-scm.com/doc). For a full instruction to work with git repository, please see [here](https://git-scm.com/doc).
This document is only used to demonstrate git operations for certain nexus-e-related questions and use cases: This document is only used to demonstrate git operations for certain nexus-e-related questions and use cases:
- [How do I get the repository?](#how-do-i-get-the-repository) - [How do I get the repository?](#how-do-i-get-the-repository)
- Short answer: you "git clone" it from <https://gitlab.ethz.ch/xyan/nexus-e.git> to a local folder. - Short answer: you "git clone" it from <https://gitlab.ethz.ch/nexus-e/nexus-e-framework.git> to a local folder.
- [What is the structure of the repository?](#what-is-the-structure-of-the-repository) - [What is the structure of the repository?](#what-is-the-structure-of-the-repository)
- Short answer: it is an overarching reposity called "nexus-e" containing sub-repositories ("[submodules](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules)" is the official term in git). - Short answer: it is an overarching reposity called "nexus-e" containing sub-repositories ("[submodules](https://www.git-scm.com/book/en/v2/Git-Tools-Submodules)" is the official term in git).
- [I want to make changes in my own module. What should I do first?](#i-want-to-make-changes-in-my-own-module-what-should-i-do-first) - [I want to make changes in my own module. What should I do first?](#i-want-to-make-changes-in-my-own-module-what-should-i-do-first)
...@@ -30,22 +30,15 @@ Why GitKraken: ...@@ -30,22 +30,15 @@ Why GitKraken:
(3) Initialize the submodules (select "Yes") (3) Initialize the submodules (select "Yes")
![](images/gitkraken-initialize-submodules.png) ![](images/gitkraken-initialize-submodules.png)
Afterwards, you will see the following window. Afterwards, you will see submodules getting initialized one by one (In the screenshot below there are 7 submodules. Since January 2021, it is reduced to 5 submodules.):
![](images/gitkraken-finish-clone.png) ![](images/gitkraken-finish-clone.png)
The operations in the screenshots above are equivalent to the following commands in a terminal.
```
cd /Users/xyan/Documents/repository
mkdir nexus-e
git clone --recursive https://gitlab.ethz.ch/xyan/nexus-e.git
```
#### What is the structure of the repository? #### What is the structure of the repository?
To help with understanding, we show both interfactes in GitKraken (left) and in the repository (right). To help with understanding, we show both interfactes in GitKraken (left) and in the repository (right).
![](images/gitkraken-repo-structure.png) ![](images/gitkraken-repo-structure.png)
#### I want to make changes in my own module. What should I do first? #### I want to make changes in my own module. What should I do first?
For example, you want to make changes in the "Shared" module. For example, you want to make changes in the "Shared" module. Note: Since January 2021, "Shared" is not a submodule anymore but a folder directly under the Nexus-e repository, but the procedures demonstrated here can be applied to any submodules.
(1) Open the submodule "Shared". (1) Open the submodule "Shared".
![](images/gitkraken-open-shared.png) ![](images/gitkraken-open-shared.png)
(2) After entering the submodule "Shared", you might see such a structure. (2) After entering the submodule "Shared", you might see such a structure.
...@@ -55,8 +48,8 @@ For example, you want to make changes in the "Shared" module. ...@@ -55,8 +48,8 @@ For example, you want to make changes in the "Shared" module.
(4) Now your own branch is at the same level as "master". (4) Now your own branch is at the same level as "master".
![](images/gitkraken-after-fast-forward.png) ![](images/gitkraken-after-fast-forward.png)
(5) Sometimes you might need to update other modules as well. (5) Sometimes you might need to update other modules as well.
E.g., if your change in the "Shared" module depends on the newest changes in the "Run_Nexuse" module which is in the "target_branch" branch (doesn't have to be the "master" branch), you will need to go through a similar procedure: E.g., if your change in the "Shared" module depends on the newest changes in the "CentIv" module which is in the "target_branch" branch (doesn't have to be the "master" branch), you will need to go through a similar procedure:
- Enter "Run_Nexuse" submodule. - Enter "CentIv" submodule.
- Fast-forward your own branch to the "target_branch". - Fast-forward your own branch to the "target_branch".
(6) In the end, you could enter all submodules one by one to make sure that you are at the right place in all of them. (6) In the end, you could enter all submodules one by one to make sure that you are at the right place in all of them.
...@@ -121,6 +114,7 @@ In this section, we assume that you already have Nexus-e codes on Euler, so you ...@@ -121,6 +114,7 @@ In this section, we assume that you already have Nexus-e codes on Euler, so you
#### I have fully tested my changes in my own module. What should I do now? #### I have fully tested my changes in my own module. What should I do now?
For example, you have made changes on the branch "florian" in the submodule "Gemel". The changes have been tested together with the updated module "Run_Nexuse". Now you are confident about the codes and you want other researchers also use your updates. For example, you have made changes on the branch "florian" in the submodule "Gemel". The changes have been tested together with the updated module "Run_Nexuse". Now you are confident about the codes and you want other researchers also use your updates.
Note: Since January 2021, "Run_Nexuse" is not a submodule anymore but a folder directly under the Nexus-e repository, but the procedures demonstrated here can be applied to any submodules.
(1) Enter the "Gemel" submodule. (1) Enter the "Gemel" submodule.
![](images/gitkraken-enter-gemel.png) ![](images/gitkraken-enter-gemel.png)
(2) Checkout origin/master (2) Checkout origin/master
......
...@@ -2,27 +2,11 @@ ...@@ -2,27 +2,11 @@
#### Get permissions #### Get permissions
Before setting up, you need permissions to access the codes and the input database. Email the following people to ask for the corresponding permissions. Before setting up, ask for permission from <nexus-e@ethz.ch> to access the codes and the input database.
```Note:: |:warning:| Currently, the codes are only accessible with an ETH account. ```Note:: |:warning:| Currently, the codes and databases are only accessible with an ETH account.
``` ```
- 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,
- 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):
- permission for the overarching **Nexus-e** repository (<https://gitlab.ethz.ch/xyan/nexus-e.git>)
#### Local setup #### 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** 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.
...@@ -39,7 +23,7 @@ The instructions here use **command lines**. If you have a GUI tool for git, you ...@@ -39,7 +23,7 @@ The instructions here use **command lines**. If you have a GUI tool for git, you
- Clone the overarching repository with this command: - Clone the overarching repository with this command:
```git clone --recursive https://gitlab.ethz.ch/xyan/nexus-e.git``` ```git clone --recursive https://gitlab.ethz.ch/nexus-e/nexus-e-framework.git```
You will be asked for your username and password for the repository and its submodules. You will be asked for your username and password for the repository and its submodules.
...@@ -89,7 +73,7 @@ You could skip this section if you don't plan to run the whole Nexus-e platform ...@@ -89,7 +73,7 @@ You could skip this section if you don't plan to run the whole Nexus-e platform
- Create a **javaclasspath.txt** file in the **Matlab preferences folder**. - 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. - In the **javaclasspath.txt** file, write the path to the connector .jar file that you just copied.
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`. 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`.
- Reload Matlab - Reload Matlab
...@@ -114,7 +98,7 @@ You could skip this section if you don't plan to run the whole Nexus-e platform ...@@ -114,7 +98,7 @@ You could skip this section if you don't plan to run the whole Nexus-e platform
- **Python** (3.8.6 is recomended. Python 3.9 is not compatible with Gurobi 9.0.x yet.) - **Python** (3.8.6 is recomended. Python 3.9 is not compatible with Gurobi 9.0.x yet.)
```eval_rst ```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. |: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.
``` ```
- Python packages: install the required packages listed in `requirements.txt`. - Python packages: install the required packages listed in `requirements.txt`.
...@@ -162,13 +146,14 @@ So far you should have already downloaded MySQL from the section [Connect with t ...@@ -162,13 +146,14 @@ So far you should have already downloaded MySQL from the section [Connect with t
- 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). - 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. - 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). - 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: - Test if ImageMagick works:
- Open Windows command prompt and brows to folder that contains a pdf file, e.g., testch.pdf - Open Windows command prompt and brows to folder that contains a pdf file, e.g., testch.pdf
- Use the following command to identify file: magic identify testch.pdf - Use the following command to identify file: magic identify testch.pdf
- Use the following command to convert file: convert testch.pdf testch.jpg - Use the following command to convert file: convert testch.pdf testch.jpg
- Instructions for Mac:
##### 4. Run Nexus-e ##### 4. Run Nexus-e
...@@ -263,7 +248,7 @@ To check whether you are added to the user group, use command line ssh to Euler ...@@ -263,7 +248,7 @@ To check whether you are added to the user group, use command line ssh to Euler
- Create a folder where you want to put the codes - Create a folder where you want to put the codes
- cd to that folder - cd to that folder
- Clone the overarching repository with this command: - Clone the overarching repository with this command:
```git clone --recursive https://gitlab.ethz.ch/xyan/nexus-e.git``` ```git clone --recursive https://gitlab.ethz.ch/nexus-e/nexus-e-framework.git```
You will be asked for your username and password for the repository and its submodules. 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: tThe `Results` folder will be automatically generated when you run Nexus-e. In the end, the folder will look like the screenshot below. Note: tThe `Results` folder will be automatically generated when you run Nexus-e.
......
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