DEPRECATED: Installing HNN on Mac OS (Docker Desktop)
- Supported alternative: Python install instructions
- Download the installer image (version 2.7.11 tested): https://www.xquartz.org/
- Run the XQuartz.pkg installer within the image, granting privileges when requested.
Prerequisite: Docker Desktop
- In order to download Docker Desktop, you’ll need to sign up for a Docker Hub account. It only requires an email address to confirm the account. Sign up here: Docker Hub Sign-up
- Download the installer image (requires logging in to your Docker Hub account): Docker Desktop
- Run the Docker Desktop installer, moving docker to the applications folder.
- Start the Docker application, acknowledging that it was downloaded from the Internet and you still want to open it.
- Log into your Docker Hub account if prompted by the Docker Desktop application.
- The Docker Desktop icon will appear in the taskbar with the message “Docker Desktop is starting”, Followed by “Docker Desktop is now up and running!”.
Increase the number of cores that Docker can use (we recommend all cores) by clicking on the Docker Desktop icon in the taskbar and then clicking “Preferences”. Choose the “Advanced” tab, and adjust with the slider. Then restart Docker Desktop to apply the setting.
Download the HNN repo. Choose one of the following methods:
- Download the source code (zip) for our latest HNN release from our GitHub releases page
- Open the .zip file and click “Extract all”. Choose any destination folder on your machine.
Open a cmd.exe window and change to the directory part of the extracted HNN release shown below:
Start the Docker container using the
hnn_docker.shscript. For the first time, we will pass the
-uoption in case there were any previous versions of the docker image on your computer. You can omit the
./hnn_docker.sh -u start
- The HNN GUI should show up. Make sure that you can run simulations by clicking the ‘Run Simulation’ button. This will run a simulation with the default configuration. After it completes, graphs should be displayed in the main window.
- If the GUI doesn’t show up, check the Docker troubleshooting section (also links the bottom of this page)
- You can now proceed to running the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
- A subdirectory called “hnn_out” is created in your home directory and is where simulation results and parameter files will be saved.
To quit HNN and shut down container, first press ‘Quit’ within the GUI. Then run
$ ./hnn_docker.sh stop Stopping HNN container requested Performing pre-checks before starting HNN -------------------------------------- Checking if Docker is working... ok hnn_container Successfully stopped HNN container
Upgrading to a new version of HNN
To just pull the latest docker image from Docker Hub:
Instead to upgrade and start the newest GUI:
./hnn_docker.sh -u start
Editing files within HNN container
You may want run commands or edit files within the container. To access a command shell in the container, start the container using
./hnn_docker.sh start in one terminal window to start hnn in the background and then run
docker exec in another terminal window:
$ docker exec -ti hnn_container bash hnn_user@hnn-container:/home/hnn_user/hnn_source_code$
If you’d like to be able to copy files from the host OS without using the shared directory, you can do so directly with
If you want to remove the container and 1.6 GB HNN image, run the following commands from a terminal window.
You can then remove Docker Desktop by removing it from your Applications folder.
For errors related to Docker, please see the Docker troubleshooting section
If you run into other issues with the installation, please open an issue on our GitHub. Our team monitors these issues and will be able to suggest possible fixes.
For other HNN software issues, please visit the HNN bulletin board