diff --git a/workshop-instructions/instructions.html b/workshop-instructions/instructions.html index d90e4d4..e8fc8bd 100644 --- a/workshop-instructions/instructions.html +++ b/workshop-instructions/instructions.html @@ -88,7 +88,12 @@

Table of Contents

-

Cloning the HNN-Data Repository

-

To follow along with the workshop, you’ll need the hnn-data repository on your local machine / virtual environment.

-

You can download the file here or you can run the following command to clone the repository.

+

Workshop Sign-In (Optional but Encouraged)

+

Please consider ‘signing in’ to the workshop by providing your institution/location, position, and field of study. This information is used in reporting on milestones for the grants that continue to fund our dissemination and development. We don’t ask for name or email, and the form should take no more than 30 seconds to complete.

+

Click here to navigate to our Virtual Sign-In Form.

+

+Thanks for your support. 😁 +

+

Workshop Materials

+

HNN-Core GUI Tutorial

+

This section of the workshop will require you to use HNN-Core GUI. See the sections below outlining the different installation methods available for getting started with the GUI.

+

To follow along with the workshop, you’ll also need to clone or download the hnn-data repository.

+

Click here to download the hnn-data folder directly. Altenatively, you can clone the repository with the follwing command.

git clone https://github.com/jonescompneurolab/hnn-data.git
-

If you already cloned the hnn-data repository on your machine, be sure to update it to include the latest changes.

-
cd hnn-data
-git pull
+

HNN-Core Python Tutorial

+

The HNN-Core Python tutorial will utilize the following Google CoLab notebook, which can also be downloaded as an .ipynb file and run locally: hnn-workshop-materials

Preferred Installation Method: Google CoLab

This installation method is the quickest way to get up and running with the HNN-Core GUI, though it does require a Google Account. If you do not have a Google account, you can either create one for free to run the notebook, or try one of the other installation methods listed below.

-

We have created a Google CoLab notebook that allows you to run the HNN-Core GUI out of your browser, with access to your local filesystem. Click here to open the notebook, which includes instructions on how to get set up.

+

We have created a Google CoLab notebook that allows you to run the HNN-Core GUI out of your browser, with access to your local filesystem. Click here to open the notebook, which includes instructions on how to get set up.

Alternative Installation Methods

Warning: You may experience considerable lag in navigating the virtual desktop environment if you do not have a strong WiFi connection. If you experience this issue, we encourage you to try one of the other installation methods here to get started.

Oscar On Demand (OOD) Virtual Desktop

@@ -169,49 +181,49 @@

Launching the Desktop App on OscarLaunching HNN-Core GUI via Oscar

With the Oscar desktop instance open, launch a Terminal via the “Terminal Emulator” at the bottom of the Desktop or via the Applications drop-down at the top-left of the Desktop.

Type the following into the terminal to activate the environment.

-
module purge
-module load python/3.11
-module load  hpcx-mpi/4.1.5rc2
-source /oscar/data/ccv_workshop/hnn_env/bin/activate
+
module purge
+module load python/3.11
+module load  hpcx-mpi/4.1.5rc2
+source /oscar/data/ccv_workshop/hnn_env/bin/activate

Within the same terminal with the hnn_env activated, type the following to launch the GUI.

-
hnn-gui
+
hnn-gui

Launching HNN-Core (Python) via Oscar

From the Oscar virtual desktop, open a new terminal and run the following commands.

-
module purge
-module load python/3.11
-module load  hpcx-mpi/4.1.5rc2
-source /oscar/data/ccv_workshop/hnn_env/bin/activate
-
-git clone https://github.com/jasmainak/hnn-workshop-materials.git
-cd hnn-workshop-materials/
-jupyter lab # or `jupyter notebook` alternatively
+
module purge
+module load python/3.11
+module load  hpcx-mpi/4.1.5rc2
+source /oscar/data/ccv_workshop/hnn_env/bin/activate
+
+git clone https://github.com/jasmainak/hnn-workshop-materials.git
+cd hnn-workshop-materials/
+jupyter lab # or `jupyter notebook` alternatively

Installing HNN-Core GUI on Your Local Machine without Conda

You can easily install HNN-Core GUI on your local machine with pip.

To do so, open a Terminal and and enter the following command:

For bash/Powershell

-
pip install --pre hnn-core[gui]
+
pip install --pre hnn-core[gui]

For zsh

-
pip install --pre hnn-core'[gui]'
+
pip install --pre hnn-core'[gui]'

Once installed, you can launch the GUI with the following command.

-
hnn-gui
+
hnn-gui

Note that you will not be able to utilize the MPI backend to run simulation in parallel without also installing MPI on your machine. We recommend using the Conda install method below if you would like to utilize MPI, as it significantly streamlines the MPI setup process.

For our workshops, we will be running simulations with only a few trials at most, and so MPI is not strictly necessary to keep up with the materials.

Installing HNN-Core GUI on Your Local Machine via Conda

Creating a Conda Env and Installing Dependencies

Note: We recommend using use Windows Subsystem for Linux (WSL) to run HNN on Windows machines. Installation instructions can be found here

Start by creating a new conda environment. We recommend creating an environment with the fewest number of dependencies to speed up the installation process.

-
conda create --name hnn_core_gui python=3.11 --no-default-packages
-conda activate hnn_core_gui
-pip install --pre hnn-core[gui]
+
conda create --name hnn_core_gui python=3.11 --no-default-packages
+conda activate hnn_core_gui
+pip install --pre hnn-core[gui]

Installing MPI for Parallel Simulations

To run simulations in parallel across multiple cores, which dramatically speeds up siuations, you’ll need to set up the MPI backend.

-
conda activate hnn_core_gui # activate the environment if needed
-conda install -y openmpi mpi4py
-pip install psutil
+
conda activate hnn_core_gui # activate the environment if needed
+conda install -y openmpi mpi4py
+pip install psutil

Additionally, for MacOS, run the following command.

-
export DYLD_FALLBACK_LIBRARY_PATH=${CONDA_PREFIX}/lib
+
export DYLD_FALLBACK_LIBRARY_PATH=${CONDA_PREFIX}/lib

More detailedd instructions are available on our parallel backends page.

Launch the GUI

You can now launch the GUI from within your conda environemnt.

-
conda activate hnn_core_gui # activate the environment if needed
-hnn-gui
+
conda activate hnn_core_gui # activate the environment if needed
+hnn-gui
diff --git a/workshop-instructions/instructions.md b/workshop-instructions/instructions.md index 31494f1..951c215 100644 --- a/workshop-instructions/instructions.md +++ b/workshop-instructions/instructions.md @@ -1,6 +1,9 @@ **Table of Contents** -- [Cloning the HNN-Data Repository](#cloning-the-hnn-data-repository) +- [Workshop Sign-In (Optional but Encouraged)](#workshop-sign-in-optional-but-encouraged) +- [Workshop Materials](#workshop-materials) + - [HNN-Core GUI Tutorial](#hnn-core-gui-tutorial) + - [HNN-Core Python Tutorial](#hnn-core-python-tutorial) - [Preferred Installation Method: Google CoLab](#preferred-installation-method-google-colab) - [Alternative Installation Methods](#alternative-installation-methods) - [Oscar On Demand (OOD) Virtual Desktop](#oscar-on-demand-ood-virtual-desktop) @@ -14,28 +17,38 @@ - [Installing MPI for Parallel Simulations](#installing-mpi-for-parallel-simulations) - [Launch the GUI](#launch-the-gui) +# Workshop Sign-In (Optional but Encouraged) -# Cloning the HNN-Data Repository -To follow along with the workshop, you'll need the [hnn-data repository](https://github.com/jonescompneurolab/hnn-data) on your local machine / virtual environment. +Please consider 'signing in' to the workshop by providing your institution/location, position, and field of study. This information is used in reporting on milestones for the grants that continue to fund our dissemination and development. We don't ask for name or email, and the form should take no more than 30 seconds to complete. -You can download the file [here](https://github.com/jonescompneurolab/hnn-data/archive/refs/heads/main.zip) or you can run the following command to clone the repository. +Click [here](https://forms.gle/YnZX9ZRm8WvWpAGU7) to navigate to our Virtual Sign-In Form. + +

Thanks for your support. 😁

+ + +# Workshop Materials + +## HNN-Core GUI Tutorial + +This section of the workshop will require you to use HNN-Core GUI. See the sections below outlining the different installation methods available for getting started with the GUI. + +To follow along with the workshop, you'll also need to clone or download the [hnn-data repository](https://github.com/jonescompneurolab/hnn-data). + +Click [here](https://github.com/jonescompneurolab/hnn-data/archive/refs/heads/main.zip) to download the hnn-data folder directly. Altenatively, you can clone the repository with the follwing command. ```bash git clone https://github.com/jonescompneurolab/hnn-data.git ``` -If you already cloned the hnn-data repository on your machine, be sure to update it to include the latest changes. +## HNN-Core Python Tutorial -```bash -cd hnn-data -git pull -``` +The HNN-Core Python tutorial will utilize the following Google CoLab notebook, which can also be downloaded as an .ipynb file and run locally: [hnn-workshop-materials](https://colab.research.google.com/drive/1CvNTB_puonJiVvHmFhKhrr_CjmrfbgVB?usp=sharing) # Preferred Installation Method: Google CoLab This installation method is the quickest way to get up and running with the HNN-Core GUI, though it does require a Google Account. If you do not have a Google account, you can either create one for free to run the notebook, or try one of the other installation methods listed below. -We have created a Google CoLab notebook that allows you to run the HNN-Core GUI out of your browser, with access to your local filesystem. Click here to open the notebook, which includes instructions on how to get set up. +We have created a Google CoLab notebook that allows you to run the HNN-Core GUI out of your browser, with access to your local filesystem. Click here to open the notebook, which includes instructions on how to get set up. # Alternative Installation Methods