From 3c0097721c040e3fd5724a239ce9d97cf884544e Mon Sep 17 00:00:00 2001 From: Ajoke Yusuf Date: Fri, 11 Oct 2024 09:04:12 +0100 Subject: [PATCH 1/3] Create DEVELOPMENT.md Added the getting started and Ersilia Artifacts session --- DEVELOPMENT.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 00000000..05b776f9 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,92 @@ +# Development +This file highlight the installation process of getting started with Ersilia, Ersilia Artifacts and Creating a PR. + +## Getting Started +Ersilia can be run either on local computer or with the use of GitHub codespace. On your local computer, ersilia is designed to run specific environment +namely: **Linux and Linux-like environment** (MacOS, WSL). + +- ### Installation of Ersilia on local computer +To get started with Ersilia installation, there are few dependencies that needs to be installed before proceeding to installation of Ersilia. Please check the package requirement +in the [Installation Guide](https://ersilia.gitbook.io/ersilia-book/ersilia-model-hub/installation) +1. Once the required dependencies has been met, open a terminal and set up a Conda environment. + +``` +# create a conda environment +conda create -n ersilia python=3.10 +# activate the environment +conda activate ersilia +``` +2. Clone the repository and run to install the Ersilia Python package. +``` +# clone from github +git clone https://github.com/ersilia-os/ersilia.git +cd ersilia +# install with pip (use -e for developer mode) +pip install -e . +``` +3. To test that the CLI works, explore this command +``` +# output to see command options for ersilia +ersilia --help +``` +4. Once ersilia is recognized in the CLI, test any model of your choice. +- First, you can check the list of available model in ersilia catalog +``` +#see ersilia's model catalog +ersilia catalog +``` +- Next, you can run the model +``` +ersilia -v fetch eos2ta5 #fetch a model +ersilia serve eos2ta5 #serve a model +ersilia -v api run -i "CCCC" #run a model +``` + +Note: The usage -v (verbose) flag is of utmost importance for developers as it provides detailed logs which helps to debug and troubleshoot issues. + +- ### Using GitHub Codespace +If difficulties are encountered when setting up Ersilia locally, another cloud-based development environment which suppoort linux is a great alternative. +GitHub codespaces allows you to run and develop Ersilia directly from your browser. + +To use Github Codespaces: + + **1. Fork and Clone the Repository** + + - Navigate [Ersilia repository](https://github.com/ersilia-os/ersilia) on GitHub. + - Click on the **Fork** button in the top right corner to create a fork. + - Go to the forked repository, Click on the <> **Code**. + - Click **Create codespace**. + +A pop up page "Setting up your codespace" is displayed on the screen. After a while, the codespace is created in a browser-based version using the built-in +Visual studio code interface + +**2. Setting Up Codespace Environment** + +- Open the terminal in codespace. To ensure you are in the root directory +`cd ersilia` +- Run this command +`pip install -e .` + +**3. Run Ersilia Model** +- Directly from the code space terminal, you can fetch, serve and run Ersilia model. +To run a model with verbose output: +`ersilia -v run eos2ta5` + + +## Ersilia Artifacts +After successful installation of ersilia, the system creates an EOS directory in your `$HOME` path. This directory stores +ersilia artifacts that the local computer uses when doing any operation (model execution) in Ersilia. +Folders found in the `$HOME` directory includes: + +**Folders** +- dest/: stores output generated when running a model. +- isaura/: cache model prediction which stores them in the local computer +- repository/: main directory to cache models files and datasets. This prevent redundant download by storing previously fetched model +- sessions/: Tracks user session +- tmp/: stores temporary file during model execution. + + + + + + From e991c93a163c8ea37c5a5defc9ceaa81bf958a67 Mon Sep 17 00:00:00 2001 From: Ajoke Yusuf Date: Mon, 14 Oct 2024 01:13:46 +0100 Subject: [PATCH 2/3] Update DEVELOPMENT.md --- DEVELOPMENT.md | 31 ++++++++++++------------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 05b776f9..0be19aa7 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,13 +1,11 @@ # Development -This file highlight the installation process of getting started with Ersilia, Ersilia Artifacts and Creating a PR. +This file highlight the installation process of getting started with Ersilia, Ersilia Artifacts and Creating a Pull Request. ## Getting Started -Ersilia can be run either on local computer or with the use of GitHub codespace. On your local computer, ersilia is designed to run specific environment -namely: **Linux and Linux-like environment** (MacOS, WSL). +Ersilia can be run either on local computer or with the use of GitHub codespaces. Ersilia is designed to run on **Linux or Linux-like environments** namely: MacOS, Windows Sub-system for Linux (WSL) and at present is not supported on Windows systems. - ### Installation of Ersilia on local computer -To get started with Ersilia installation, there are few dependencies that needs to be installed before proceeding to installation of Ersilia. Please check the package requirement -in the [Installation Guide](https://ersilia.gitbook.io/ersilia-book/ersilia-model-hub/installation) +To get started with Ersilia installation, there are few dependencies that needs to be installed before proceeding to installation of Ersilia. Please, check the package requirement in the [Installation Guide](https://ersilia.gitbook.io/ersilia-book/ersilia-model-hub/installation) 1. Once the required dependencies has been met, open a terminal and set up a Conda environment. ``` @@ -22,7 +20,7 @@ conda activate ersilia git clone https://github.com/ersilia-os/ersilia.git cd ersilia # install with pip (use -e for developer mode) -pip install -e . +pip install -e .[test] ``` 3. To test that the CLI works, explore this command ``` @@ -30,7 +28,7 @@ pip install -e . ersilia --help ``` 4. Once ersilia is recognized in the CLI, test any model of your choice. -- First, you can check the list of available model in ersilia catalog +- First, you can check the list of available model in ersilia's catalog ``` #see ersilia's model catalog ersilia catalog @@ -44,8 +42,8 @@ ersilia -v api run -i "CCCC" #run a model Note: The usage -v (verbose) flag is of utmost importance for developers as it provides detailed logs which helps to debug and troubleshoot issues. -- ### Using GitHub Codespace -If difficulties are encountered when setting up Ersilia locally, another cloud-based development environment which suppoort linux is a great alternative. +- ### Using GitHub Codespaces +If difficulties are encountered while setting up Ersilia locally, another cloud-based development environment which suppoort linux is a great alternative. GitHub codespaces allows you to run and develop Ersilia directly from your browser. To use Github Codespaces: @@ -57,25 +55,20 @@ To use Github Codespaces: - Go to the forked repository, Click on the <> **Code**. - Click **Create codespace**. -A pop up page "Setting up your codespace" is displayed on the screen. After a while, the codespace is created in a browser-based version using the built-in -Visual studio code interface +A pop up page "Setting up your codespace" is displayed on the screen. After a while, the codespace is created in a browser-based version using the built-in Visual studio code interface -**2. Setting Up Codespace Environment** +**2. Setting Up GitHub Codespaces Environment** -- Open the terminal in codespace. To ensure you are in the root directory -`cd ersilia` -- Run this command -`pip install -e .` +- Once you open the codespaces environment, ersilia has been installed and ready for usage. To double check, you can verify by running this command `ersilia --version`. This +will display the version of ersilia installed. **3. Run Ersilia Model** - Directly from the code space terminal, you can fetch, serve and run Ersilia model. To run a model with verbose output: `ersilia -v run eos2ta5` - ## Ersilia Artifacts -After successful installation of ersilia, the system creates an EOS directory in your `$HOME` path. This directory stores -ersilia artifacts that the local computer uses when doing any operation (model execution) in Ersilia. +After successful installation of ersilia in the user's local computer, the system creates an EOS directory in the user's `$HOME` path. This directory stores ersilia artifacts that the local computer uses when doing any operation (model execution) in Ersilia. Folders found in the `$HOME` directory includes: **Folders** From 0e799d762db625d75188a4d18859820671dbbe6e Mon Sep 17 00:00:00 2001 From: Ajoke Yusuf Date: Mon, 14 Oct 2024 03:16:41 +0100 Subject: [PATCH 3/3] Add creating a PR section --- DEVELOPMENT.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 0be19aa7..e7297c37 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -78,6 +78,33 @@ Folders found in the `$HOME` directory includes: - sessions/: Tracks user session - tmp/: stores temporary file during model execution. +## Creating a Pull Request +To get started, please read and follow our [Code of Conduct](https://github.com/ersilia-os/ersilia/blob/master/CODE_OF_CONDUCT.md) + +**1. Via GitHub Codespaces Environment** +- In the codespace terminal, create a new branch +``` +git checkout -b your-branch-name +``` +- Make all necessary changes and commit them +``` +git add . +git commit -m "Description of changes made" +``` +- Push changes to GitHub +``` +git push origin your-branch-name +``` +- Click on **Create pull request** in the prompt that will be shown + +**2. Via GitHub Desktop** +- Fork the repository +- Create a new branch and name it. +- Commit your changes +- Navigate the repository,Click on **Compare & pull request** +- Set the main branch to **master** since it's the ersilia repository main branch and set the compare branch to your-branch-name +- Fill out the title section and give a brief description of any changes made +- Click **Create Pull Request**