Skip to content

Commit

Permalink
rework instructions to prioritize Colab
Browse files Browse the repository at this point in the history
  • Loading branch information
@dylansdaniels
dylansdaniels committed Aug 28, 2024
1 parent a1601f5 commit c7e39e3
Show file tree
Hide file tree
Showing 2 changed files with 126 additions and 57 deletions.
103 changes: 66 additions & 37 deletions workshop-instructions/instructions.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,14 +88,40 @@
<!-- END -->
<p><strong>Table of Contents</strong></p>
<ul>
<li><a href="#logging-into-the-oscar-virtual-environment">Logging into the Oscar Virtual Environment</a></li>
<li><a href="#cloning-the-hnn-data-repository">Cloning the HNN-Data Repository</a></li>
<li><a href="#preferred-installation-method-google-colab">Preferred Installation Method: Google CoLab</a></li>
<li><a href="#alternative-installation-methods">Alternative Installation Methods</a>
<ul>
<li><a href="#oscar-on-demand-ood-virtual-desktop">Oscar On Demand (OOD) Virtual Desktop</a>
<ul>
<li><a href="#logging-in-to-ood">Logging in to OOD</a></li>
<li><a href="#launching-the-desktop-app-on-oscar">Launching the Desktop App on Oscar</a></li>
<li><a href="#launching-hnn-core-gui-via-oscar">Launching HNN-Core GUI via Oscar</a></li>
<li><a href="#launching-hnn-core-python-via-oscar">Launching HNN-Core (Python) via Oscar</a></li>
<li><a href="#cloning-the-hnn-data-repository">Cloning the HNN-Data Repository</a></li>
<li><a href="#installing-hnn-core-gui-on-your-local-machine-via-conda">Installing HNN-Core GUI on Your Local Machine via Conda</a></li>
</ul></li>
<li><a href="#installing-hnn-core-gui-on-your-local-machine-without-conda">Installing HNN-Core GUI on Your Local Machine without Conda</a></li>
<li><a href="#installing-hnn-core-gui-on-your-local-machine-via-conda">Installing HNN-Core GUI on Your Local Machine via Conda</a>
<ul>
<li><a href="#creating-a-conda-env-and-installing-dependencies">Creating a Conda Env and Installing Dependencies</a></li>
<li><a href="#installing-mpi-for-parallel-simulations">Installing MPI for Parallel Simulations</a></li>
<li><a href="#launch-the-gui">Launch the GUI</a></li>
</ul></li>
</ul></li>
</ul>
<h2 id="logging-into-the-oscar-virtual-environment">Logging into the Oscar Virtual Environment</h2>
<h1 id="cloning-the-hnn-data-repository">Cloning the HNN-Data Repository</h1>
<p>To follow along with the workshop, you’ll need to clone the <a href="https://github.com/jonescompneurolab/hnn-data">hnn-data repository</a> to your local machine / virtual environment.</p>
<p>To do so, launch a terminal and run the following command.</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1"></a><span class="fu">git</span> clone https://github.com/jonescompneurolab/hnn-data.git</span></code></pre></div>
<p>If you already have the hnn-data repo on your machine, be sure to update it to include the latest changes</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1"></a><span class="bu">cd</span> hnn-data</span>
<span id="cb2-2"><a href="#cb2-2"></a><span class="fu">git</span> pull</span></code></pre></div>
<h1 id="preferred-installation-method-google-colab">Preferred Installation Method: Google CoLab</h1>
<p>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.</p>
<p>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 <a href="https://colab.research.google.com/drive/1yyjuEBimIu_f7_0Nf3YLwUiVOO7ZrKK3?usp=sharing">here</a> to open the notebook, which includes instructions on how to get set up.</p>
<h1 id="alternative-installation-methods">Alternative Installation Methods</h1>
<p><strong>Warning</strong>: 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.</p>
<h2 id="oscar-on-demand-ood-virtual-desktop">Oscar On Demand (OOD) Virtual Desktop</h2>
<h3 id="logging-in-to-ood">Logging in to OOD</h3>
<ol type="1">
<li><p>Go to Oscar-on-Demand (OOD): <a href="https://ood.ccv.brown.edu/pun/sys/dashboard/batch_connect/sessions">ood.ccv.brown.edu/pun/sys/dashboard/batch_connect/sessions</a></p></li>
<li><p>Select a username from the <a href="https://docs.google.com/spreadsheets/d/1NQuCULv6Nmo1n7cHnsD5ZnEYtnxPeYUWzRBvaXFvliA/edit?usp=sharing">following spreadsheet</a> and add an “X” to the appropriate cell. The “X” is to indicate that the username you selected is “in use” so another participant doesn’t try to log in with the same username/bypass code</p></li>
Expand Down Expand Up @@ -124,7 +150,7 @@ <h2 id="logging-into-the-oscar-virtual-environment">Logging into the Oscar Virtu
<li>Enter the bypass code associated with the username you selected in Step 2</li>
</ol>
<p></span></p>
<h2 id="launching-the-desktop-app-on-oscar">Launching the Desktop App on Oscar</h2>
<h3 id="launching-the-desktop-app-on-oscar">Launching the Desktop App on Oscar</h3>
<ol type="1">
<li>Choose the “Desktop (Advanced)” application. Note that this is different form the regular “Desktop” app.</li>
<li>You will see a form. Enter the following in the fields.
Expand All @@ -141,47 +167,50 @@ <h2 id="launching-the-desktop-app-on-oscar">Launching the Desktop App on Oscar</
</ul></li>
<li>Click “Launch” . It may take a minute before the “Launch Desktop” button appears.</li>
</ol>
<h2 id="launching-hnn-core-gui-via-oscar">Launching HNN-Core GUI via Oscar</h2>
<h3 id="launching-hnn-core-gui-via-oscar">Launching HNN-Core GUI via Oscar</h3>
<p>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.</p>
<p>Type the following into the terminal to activate the environment.</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1"></a><span class="ex">module</span> purge</span>
<span id="cb1-2"><a href="#cb1-2"></a><span class="ex">module</span> load python/3.11</span>
<span id="cb1-3"><a href="#cb1-3"></a><span class="ex">module</span> load hpcx-mpi/4.1.5rc2</span>
<span id="cb1-4"><a href="#cb1-4"></a><span class="bu">source</span> /oscar/data/ccv_workshop/hnn_env/bin/activate</span></code></pre></div>
<p>Within the same terminal with the <code>hnn_env</code> activated, type the following to launch the GUI.</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1"></a><span class="ex">hnn-gui</span></span></code></pre></div>
<h2 id="launching-hnn-core-python-via-oscar">Launching HNN-Core (Python) via Oscar</h2>
<p>From the Oscar virtual desktop, open a new terminal and run the following commands.</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1"></a><span class="ex">module</span> purge</span>
<span id="cb3-2"><a href="#cb3-2"></a><span class="ex">module</span> load python/3.11</span>
<span id="cb3-3"><a href="#cb3-3"></a><span class="ex">module</span> load hpcx-mpi/4.1.5rc2</span>
<span id="cb3-4"><a href="#cb3-4"></a><span class="bu">source</span> /oscar/data/ccv_workshop/hnn_env/bin/activate</span>
<span id="cb3-5"><a href="#cb3-5"></a></span>
<span id="cb3-6"><a href="#cb3-6"></a><span class="fu">git</span> clone https://github.com/jasmainak/hnn-workshop-materials.git</span>
<span id="cb3-7"><a href="#cb3-7"></a><span class="bu">cd</span> hnn-workshop-materials/</span>
<span id="cb3-8"><a href="#cb3-8"></a><span class="ex">jupyter</span> lab <span class="co"># or `jupyter notebook` alternatively</span></span></code></pre></div>
<h2 id="cloning-the-hnn-data-repository">Cloning the HNN-Data Repository</h2>
<p>To follow along with the workshop, you’ll need to clone the <a href="https://github.com/jonescompneurolab/hnn-data">hnn-data repository</a> to your local machine.</p>
<p>To do so, launch a terminal and run the following command.</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1"></a><span class="fu">git</span> clone https://github.com/jonescompneurolab/hnn-data.git</span></code></pre></div>
<p>If you already have the hnn-data repo on your machine, be sure to update it to include the latest changes</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1"></a><span class="bu">cd</span> hnn-data</span>
<span id="cb5-2"><a href="#cb5-2"></a><span class="fu">git</span> pull</span></code></pre></div>
<span id="cb3-4"><a href="#cb3-4"></a><span class="bu">source</span> /oscar/data/ccv_workshop/hnn_env/bin/activate</span></code></pre></div>
<p>Within the same terminal with the <code>hnn_env</code> activated, type the following to launch the GUI.</p>
<div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1"></a><span class="ex">hnn-gui</span></span></code></pre></div>
<h3 id="launching-hnn-core-python-via-oscar">Launching HNN-Core (Python) via Oscar</h3>
<p>From the Oscar virtual desktop, open a new terminal and run the following commands.</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb5-1"><a href="#cb5-1"></a><span class="ex">module</span> purge</span>
<span id="cb5-2"><a href="#cb5-2"></a><span class="ex">module</span> load python/3.11</span>
<span id="cb5-3"><a href="#cb5-3"></a><span class="ex">module</span> load hpcx-mpi/4.1.5rc2</span>
<span id="cb5-4"><a href="#cb5-4"></a><span class="bu">source</span> /oscar/data/ccv_workshop/hnn_env/bin/activate</span>
<span id="cb5-5"><a href="#cb5-5"></a></span>
<span id="cb5-6"><a href="#cb5-6"></a><span class="fu">git</span> clone https://github.com/jasmainak/hnn-workshop-materials.git</span>
<span id="cb5-7"><a href="#cb5-7"></a><span class="bu">cd</span> hnn-workshop-materials/</span>
<span id="cb5-8"><a href="#cb5-8"></a><span class="ex">jupyter</span> lab <span class="co"># or `jupyter notebook` alternatively</span></span></code></pre></div>
<h2 id="installing-hnn-core-gui-on-your-local-machine-without-conda">Installing HNN-Core GUI on Your Local Machine without Conda</h2>
<p>You can easily install HNN-Core GUI on your local machine with pip.</p>
<p>To do so, open a Terminal and and enter the following command:</p>
<p><strong>For bash/Powershell</strong></p>
<div class="sourceCode" id="cb6"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1"></a><span class="ex">pip</span> install --pre hnn-core[gui]</span></code></pre></div>
<p><strong>For zsh</strong></p>
<div class="sourceCode" id="cb7"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1"></a><span class="ex">pip</span> install --pre hnn-core<span class="st">&#39;[gui]&#39;</span></span></code></pre></div>
<p>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.</p>
<p>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.</p>
<h2 id="installing-hnn-core-gui-on-your-local-machine-via-conda">Installing HNN-Core GUI on Your Local Machine via Conda</h2>
<h3 id="creating-a-conda-env-and-installing-dependencies">Creating a Conda Env and Installing Dependencies</h3>
<p><strong>Note</strong>: We recommend using use Windows Subsystem for Linux (WSL) to run HNN on Windows machines. Installation instructions can be found <a href="https://learn.microsoft.com/en-us/windows/wsl/install">here</a></p>
<p>Start by creating a new conda environment. We recommend creating an environment with the fewest number of dependencies to speed up the installation process.</p>
<div class="sourceCode" id="cb6"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1"></a><span class="ex">conda</span> create --name hnn_core_gui python=3.11 --no-default-packages</span>
<span id="cb6-2"><a href="#cb6-2"></a><span class="ex">conda</span> activate hnn_core_gui</span>
<span id="cb6-3"><a href="#cb6-3"></a><span class="ex">pip</span> install --pre hnn-core[gui]</span></code></pre></div>
<p><strong>MPI Installation</strong></p>
<div class="sourceCode" id="cb8"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1"></a><span class="ex">conda</span> create --name hnn_core_gui python=3.11 --no-default-packages</span>
<span id="cb8-2"><a href="#cb8-2"></a><span class="ex">conda</span> activate hnn_core_gui</span>
<span id="cb8-3"><a href="#cb8-3"></a><span class="ex">pip</span> install --pre hnn-core[gui]</span></code></pre></div>
<h3 id="installing-mpi-for-parallel-simulations">Installing MPI for Parallel Simulations</h3>
<p>To run simulations in parallel across multiple cores, which dramatically speeds up siuations, you’ll need to set up the MPI backend.</p>
<div class="sourceCode" id="cb7"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1"></a><span class="ex">conda</span> activate hnn_core_gui <span class="co"># activate the environment if needed</span></span>
<span id="cb7-2"><a href="#cb7-2"></a><span class="ex">conda</span> install -y openmpi mpi4py</span>
<span id="cb7-3"><a href="#cb7-3"></a><span class="ex">pip</span> install psutil</span></code></pre></div>
<div class="sourceCode" id="cb9"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1"></a><span class="ex">conda</span> activate hnn_core_gui <span class="co"># activate the environment if needed</span></span>
<span id="cb9-2"><a href="#cb9-2"></a><span class="ex">conda</span> install -y openmpi mpi4py</span>
<span id="cb9-3"><a href="#cb9-3"></a><span class="ex">pip</span> install psutil</span></code></pre></div>
<p>Additionally, for MacOS, run the following command.</p>
<div class="sourceCode" id="cb8"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1"></a><span class="bu">export</span> <span class="va">DYLD_FALLBACK_LIBRARY_PATH=${CONDA_PREFIX}</span>/lib</span></code></pre></div>
<div class="sourceCode" id="cb10"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1"></a><span class="bu">export</span> <span class="va">DYLD_FALLBACK_LIBRARY_PATH=${CONDA_PREFIX}</span>/lib</span></code></pre></div>
<p>More detailedd instructions are available on our <a href="https://jonescompneurolab.github.io/hnn-core/stable/parallel.html">parallel backends</a> page.</p>
<p><strong>Lunch the GUI</strong></p>
<h3 id="launch-the-gui">Launch the GUI</h3>
<p>You can now launch the GUI from within your conda environemnt.</p>
<div class="sourceCode" id="cb9"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1"></a><span class="ex">conda</span> activate hnn_core_gui <span class="co"># activate the environment if needed</span></span>
<span id="cb9-2"><a href="#cb9-2"></a><span class="ex">hnn-gui</span></span></code></pre></div>
<div class="sourceCode" id="cb11"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-1"></a><span class="ex">conda</span> activate hnn_core_gui <span class="co"># activate the environment if needed</span></span>
<span id="cb11-2"><a href="#cb11-2"></a><span class="ex">hnn-gui</span></span></code></pre></div>
Loading

0 comments on commit c7e39e3

Please sign in to comment.