-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #6 from dylansdaniels/workshop-instructions
[WIP] Workshop instructions
- Loading branch information
Showing
7 changed files
with
487 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| <!-- START --> | ||
| <!-- html header, styling for Tutorials pages --> | ||
| <!-- note: requires stylesheet.css to be in the parent directory; see <head> section --> | ||
| <!-- copy the contents below into the appropriate sections of your html page --> | ||
|
|
||
| <!-- document setup --> | ||
|
|
||
| <html> | ||
|
|
||
| <!-- head area --> | ||
| <head> | ||
| <!-- <meta charset="utf-8" /> --> <!-- old version --> | ||
| <meta charset="utf-8" name="viewport" content="width=device-width, initial-scale=1.0" /> <!-- set the viewport https://www.w3schools.com/css/css_rwd_viewport.asp --> | ||
| <title>Tutorials - HNN</title> | ||
| <!-- import CSS style sheet from Github directory --> | ||
| <link rel = "stylesheet" type = "text/css" href = "../html-styling/stylesheet.css" /> | ||
| </head> | ||
|
|
||
| <!-- body styling --> | ||
| <body> | ||
|
|
||
| <!-- add Navbar --> | ||
| <div class="navbar"> | ||
| <div id="wrapper"> | ||
| <img src="https://hnn.brown.edu/wp-content/uploads/2018/05/mainlogo3.png" alt="HNN" scale="0"> | ||
| <a href="https://hnn.brown.edu/index.php/tutorials/#jumptutorials">TUTORIALS</a> | ||
| <a href="https://hnn.brown.edu">HOME</a> | ||
| </div> | ||
| </div> | ||
|
|
||
| <!-- add Tutorials header --> | ||
| <div class="headercontainer main"> | ||
| <div class="headertext"> </div> | ||
| </div> | ||
|
|
||
| <!-- set width for body to 900px --> | ||
| <div id="wrapper"> | ||
|
|
||
| <!-- add button to scroll to top --> | ||
| <button onclick="topFunction()" id="myBtn" title="Scroll to top">Top</button> | ||
|
|
||
| <!-- script for scroll button function --> | ||
| <script> | ||
| //Get the button: | ||
| mybutton = document.getElementById("myBtn"); | ||
| // When the user scrolls down 20px from the top of the document, show the button | ||
| window.onscroll = function() {scrollFunction()}; | ||
| function scrollFunction() { | ||
| if (document.body.scrollTop > 20 || document.documentElement.scrollTop > 20) { | ||
| mybutton.style.display = "block"; | ||
| } else { | ||
| mybutton.style.display = "none"; | ||
| } | ||
| } | ||
| // When the user clicks on the button, scroll to the top of the document | ||
| function topFunction() { | ||
| document.body.scrollTop = 0; // For Safari | ||
| document.documentElement.scrollTop = 0; // For Chrome, Firefox, IE and Opera | ||
| } | ||
| </script> | ||
|
|
||
| <!-- return to tutorials page --> | ||
| <div style="text-align:center; vertical-align: middle; padding:10px;"> | ||
| <p></p> | ||
|
|
||
| <tbody> | ||
| <tr style="border: none;"> | ||
| <td style="border: none; width: 33.3%; padding: 1px;"> | ||
| </td> | ||
|
|
||
| <td style="border: none; width: 33.3%; padding: 1px;"> | ||
| <!--<a style="text-decoration: none" href="https://hnn.brown.edu/index.php/tutorials/">--> | ||
| <p><img src="https://hnn.brown.edu/wp-content/uploads/2019/06/EEG_Brain.png" width="60" height="auto"></p> | ||
| <p style=" font-family: sans-serif; font-size: x-large; font-weight:700; color: #1156a3; border:0px; margin:0px;">Tutorials</p> | ||
| <!--</a>--> | ||
| </td> | ||
|
|
||
| <td style="border: none; width: 33.3%; padding: 1px;"> | ||
| </td> | ||
| </tr> | ||
| </tbody> | ||
| </div> | ||
|
|
||
| <!-- your contents go here --> | ||
|
|
||
| <!-- </body> --> | ||
| <!-- </html> --> | ||
| <!-- END --> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,217 @@ | ||
| <!-- START --> | ||
| <!-- html header, styling for Tutorials pages --> | ||
| <!-- note: requires stylesheet.css to be in the parent directory; see <head> section --> | ||
| <!-- copy the contents below into the appropriate sections of your html page --> | ||
|
|
||
| <!-- document setup --> | ||
|
|
||
| <html> | ||
|
|
||
| <!-- head area --> | ||
| <head> | ||
| <!-- <meta charset="utf-8" /> --> <!-- old version --> | ||
| <meta charset="utf-8" name="viewport" content="width=device-width, initial-scale=1.0" /> <!-- set the viewport https://www.w3schools.com/css/css_rwd_viewport.asp --> | ||
| <title>Tutorials - HNN</title> | ||
| <!-- import CSS style sheet from Github directory --> | ||
| <link rel = "stylesheet" type = "text/css" href = "../html-styling/stylesheet.css" /> | ||
| </head> | ||
|
|
||
| <!-- body styling --> | ||
| <body> | ||
|
|
||
| <!-- add Navbar --> | ||
| <div class="navbar"> | ||
| <div id="wrapper"> | ||
| <img src="https://hnn.brown.edu/wp-content/uploads/2018/05/mainlogo3.png" alt="HNN" scale="0"> | ||
| <a href="https://hnn.brown.edu/index.php/tutorials/#jumptutorials">TUTORIALS</a> | ||
| <a href="https://hnn.brown.edu">HOME</a> | ||
| </div> | ||
| </div> | ||
|
|
||
| <!-- add Tutorials header --> | ||
| <div class="headercontainer main"> | ||
| <div class="headertext"> </div> | ||
| </div> | ||
|
|
||
| <!-- set width for body to 900px --> | ||
| <div id="wrapper"> | ||
|
|
||
| <!-- add button to scroll to top --> | ||
| <button onclick="topFunction()" id="myBtn" title="Scroll to top">Top</button> | ||
|
|
||
| <!-- script for scroll button function --> | ||
| <script> | ||
| //Get the button: | ||
| mybutton = document.getElementById("myBtn"); | ||
| // When the user scrolls down 20px from the top of the document, show the button | ||
| window.onscroll = function() {scrollFunction()}; | ||
| function scrollFunction() { | ||
| if (document.body.scrollTop > 20 || document.documentElement.scrollTop > 20) { | ||
| mybutton.style.display = "block"; | ||
| } else { | ||
| mybutton.style.display = "none"; | ||
| } | ||
| } | ||
| // When the user clicks on the button, scroll to the top of the document | ||
| function topFunction() { | ||
| document.body.scrollTop = 0; // For Safari | ||
| document.documentElement.scrollTop = 0; // For Chrome, Firefox, IE and Opera | ||
| } | ||
| </script> | ||
|
|
||
| <!-- return to tutorials page --> | ||
| <div style="text-align:center; vertical-align: middle; padding:10px;"> | ||
| <p></p> | ||
|
|
||
| <tbody> | ||
| <tr style="border: none;"> | ||
| <td style="border: none; width: 33.3%; padding: 1px;"> | ||
| </td> | ||
|
|
||
| <td style="border: none; width: 33.3%; padding: 1px;"> | ||
| <!--<a style="text-decoration: none" href="https://hnn.brown.edu/index.php/tutorials/">--> | ||
| <p><img src="https://hnn.brown.edu/wp-content/uploads/2019/06/EEG_Brain.png" width="60" height="auto"></p> | ||
| <p style=" font-family: sans-serif; font-size: x-large; font-weight:700; color: #1156a3; border:0px; margin:0px;">Workshop Instructions</p> | ||
| <!--</a>--> | ||
| </td> | ||
|
|
||
| <td style="border: none; width: 33.3%; padding: 1px;"> | ||
| </td> | ||
| </tr> | ||
| </tbody> | ||
| </div> | ||
|
|
||
| <!-- your contents go here --> | ||
|
|
||
| <!-- </body> --> | ||
| <!-- </html> --> | ||
| <!-- END --> | ||
| <p><strong>Table of Contents</strong></p> | ||
| <ul> | ||
| <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> | ||
| </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> | ||
| <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> | ||
| <li><p>Enter your selected username into ‘Username’ field of the login page</p></li> | ||
| <li><p>Enter the password: HNNws2024*</p></li> | ||
| </ol> | ||
| <p><img src="imgs/oscar_login.png" width="400" /></p> | ||
| <ol start="5" type="1"> | ||
| <li><p> | ||
| From the DUO authentication screen, select “Other options” and then choose “Bypass code” | ||
| </p></li> | ||
| </ol> | ||
| <table> | ||
| <thead> | ||
| <tr class="header"> | ||
| <th><img src="imgs/duo_01.png" width="200" /></th> | ||
| <th><img src="imgs/duo_02.png" width="200" /></th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| </tbody> | ||
| </table> | ||
| <ol start="6" type="1"> | ||
| <li><p> | ||
| Enter the bypass code associated with the username you selected in Step 2 | ||
| </p></li> | ||
| </ol> | ||
| <h3 id="launching-the-desktop-app-on-oscar">Launching the Desktop App on Oscar</h3> | ||
| <ol type="1"> | ||
| <li><p>Choose the “Desktop (Advanced)” application. Note that this is different form the regular “Desktop” app.</p></li> | ||
| <li><p>You will see a form. Enter the following in the fields.</p> | ||
| <ul> | ||
| <li>Account: [Leave Blank]</li> | ||
| <li>Desktop Environment: xfce</li> | ||
| <li>Number of Hours: 3</li> | ||
| <li>Partition: batch</li> | ||
| <li>Num Cores: 8</li> | ||
| <li>Num GPUs: 1 [This number does not matter]</li> | ||
| <li>Memory (GB): 8</li> | ||
| <li>Reservation: hnn-workshop</li> | ||
| <li>Slurm Features: [Leave Blank]</li> | ||
| </ul></li> | ||
| <li><p>Click “Launch” . It may take a minute before the “Launch Desktop” button appears.</p></li> | ||
| </ol> | ||
| <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="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></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">'[gui]'</span></span></code></pre></div> | ||
| <p>Once installed, you can launch the GUI with 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="ex">hnn-gui</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="cb9"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1"></a><span class="ex">conda</span> create --name hnn_core_gui python=3.11 --no-default-packages</span> | ||
| <span id="cb9-2"><a href="#cb9-2"></a><span class="ex">conda</span> activate hnn_core_gui</span> | ||
| <span id="cb9-3"><a href="#cb9-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="cb10"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb10-1"><a href="#cb10-1"></a><span class="ex">conda</span> activate hnn_core_gui <span class="co"># activate the environment if needed</span></span> | ||
| <span id="cb10-2"><a href="#cb10-2"></a><span class="ex">conda</span> install -y openmpi mpi4py</span> | ||
| <span id="cb10-3"><a href="#cb10-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="cb11"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb11-1"><a href="#cb11-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> | ||
| <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="cb12"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb12-1"><a href="#cb12-1"></a><span class="ex">conda</span> activate hnn_core_gui <span class="co"># activate the environment if needed</span></span> | ||
| <span id="cb12-2"><a href="#cb12-2"></a><span class="ex">hnn-gui</span></span></code></pre></div> |
Oops, something went wrong.