diff --git a/RUN_INSTRUCTIONS.md b/RUN_INSTRUCTIONS.md new file mode 100644 index 0000000..19c6334 --- /dev/null +++ b/RUN_INSTRUCTIONS.md @@ -0,0 +1,122 @@ +# Running on a Server + +This guide outlines the steps to set up and run **PatientX** on a server, including configuring a new installation directory, creating a virtual environment, and running the required scripts. + +--- + +## 1. Creating a tmux Session (OPTIONAL but HIGHLY recommended) + +Please reference [`tmux` explanation documentation](WHY_TMUX.md) for more details on why to use `tmux` + +To create a new session, run + +```bash +tmux new -s session_name +``` + +--- + +## 2. SSH into HPC Cluster + +SSH into the HPC platform where you would like to run the PatientX code + +--- + +## 3. Creating a Virtual Environment in Python + +Virtual environments are essential for managing dependencies and avoiding conflicts between different projects. This guide will walk you through creating and activating a virtual environment using `venv`. + +--- + +### Prerequisites + +- Make sure Python 3.10+ is installed on your system. You can check by running: + + ```bash + python --version + ``` + + or + + ```bash + python3 --version + ``` + +--- + +### Creating a Virtual Environment + +Virtual environments can help us manage dependecies across projects and ensure there are no conflicting dependencies. To create a virtual environment, use the following command: + +```bash +python -m venv {ENV_NAME} +``` + +This will create a new directory called myenv containing the virtual environment. + +--- + +### Activating the Virtual Environment + +To activate the new virtual environment + +**On Windows** +```powershell +{ENV_NAME}\Scripts\Activate +``` + +**On macOS and Linux** +```zsh +source {ENV_NAME}/bin/activate +``` + + +## 4. Installing Dependencies + +All dependecies and necessary packages for `PatientX.AI` can be installed by running + +``` +pip install -e . +``` + +--- + +## 5. Start Ollama Server (optional - for LLM representation model) + +### Install Ollama + +Install [ollama](https://ollama.com/) by either going through their documentation or, if you do not have sudo access, by running +``` +./script/install.sh +``` + +### Run Ollama Server + +Run ollama server in the background by running +```bash +ollama serve & +``` + +### Run LLM model +Run the chosen model using +```bash +ollama run model-name & +``` + +--- + +## 6. Run PatientX.AI Code + +To run the PatientX.AI code + +1. Update the config file with your desired parameters +2. Run the pipeline using +```bash +python src/PatientX/run.py +``` +3. For help, run +```bash +python src/PatientX/run.py --help +``` + +For further assistance, consult the **PatientX** documentation or contact the development team. diff --git a/WHY_TMUX.md b/WHY_TMUX.md new file mode 100644 index 0000000..6eae80c --- /dev/null +++ b/WHY_TMUX.md @@ -0,0 +1,38 @@ +# Tmux: Why Use It and How to Start a Session + +## Why Use Tmux? +[Tmux (Terminal Multiplexer)](https://github.com/tmux/tmux/wiki) is a powerful tool that allows you to: + +- **Manage Multiple Terminal Sessions:** Run multiple shell sessions within a single window and easily switch between them. +- **Persistent Sessions:** Keep your sessions running even after disconnecting, which is particularly useful for SSH connections. **This can be particularly useful here since running the full PatientX.AI may take some time depending on the size of the dataset and model configuration. Without `tmux`, if the ssh connection disconnects, the code may not run to completion** +- **Efficient Workflow:** Split your terminal into multiple panes, allowing you to work on different tasks simultaneously. + +## Basic Tmux Commands + +### Start a New Session +```bash +tmux new -s session_name +``` +This creates a new session named `session_name`. + +### Detach from a Session +To detach from a session without stopping it, press: +``` +Ctrl + b, then d +``` + +### List all Sessions +To list all running sessions +``` +tmux ls +``` + +### Reattach to an Existing Session +To reattach to an existing session +``` +tmux attach -t session_name +``` + +## Learn More + +For more details and advanced usage, refer to the [official tmux documentation](https://github.com/tmux/tmux/wiki)