Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MRG: docs for hnn-core integration #280

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions installer/centos/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# HNN "Python" install (CentOS)
# HNN install (CentOS)

The script below assumes that it can update OS packages for python and prerequisites for HNN.

Expand Down Expand Up @@ -33,18 +33,20 @@ The script below assumes that it can update OS packages for python and prerequis

## Upgrading to a new version of HNN

HNN Releases can be seen on the [GitHub releases page](https://github.com/jonescompneurolab/hnn/releases/). You can also be notified of new releases by watching the hnn [repository on GitHub](https://github.com/jonescompneurolab/hnn/).
HNN Releases can be found on the [GitHub releases page](https://github.com/jonescompneurolab/hnn/releases/). You can also be notified of new releases by watching the hnn [repository on GitHub](https://github.com/jonescompneurolab/hnn/).

To download the latest release, use the following commands within an Ubuntu terminal:
To download the latest HNN release:

```bash
curl --remote-name https://github.com/jonescompneurolab/hnn/releases/latest/download/hnn.tar.gz
mkdir hnn_source_code
tar -x --strip-components 1 -f hnn.tar.gz -C hnn_source_code
cd hnn_source_code
make
python3 hnn.py
```

If you are using `git`, then run `git pull origin master` from the source code directory.

## Troubleshooting

If you run into other issues with the installation, please [open an issue on our GitHub](https://github.com/jonescompneurolab/hnn/issues). Our team monitors these issues and will investigate possible fixes.
Expand Down
2 changes: 1 addition & 1 deletion installer/centos/hnn-centos6.sh
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ sudo yum -y install python34-setuptools
sudo easy_install-3.4 pip
pip3 install --upgrade matplotlib --user
pip3 install --upgrade nlopt scipy --user
pip3 install hnn-core
pip3 install https://api.github.com/repos/jonescompneurolab/hnn-core/zipball/master
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we can draft a minor release of hnn-core to go with the release of hnn ...

sudo yum -y install ncurses-devel
sudo yum -y install openmpi openmpi-devel
sudo yum -y install libXext libXext-devel
Expand Down
2 changes: 1 addition & 1 deletion installer/docker/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ LABEL org.label-schema.build-date=$BUILD_DATE \
org.label-schema.schema-version=$VCS_TAG

# install hnn-core
RUN sudo pip install hnn-core
RUN sudo pip install https://api.github.com/repos/jonescompneurolab/hnn-core/zipball/master

# install HNN
RUN sudo apt-get update && \
Expand Down
81 changes: 32 additions & 49 deletions installer/mac/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# HNN "Python" install (Mac OS)
# HNN install (Mac OS)

## Opening a terminal window

Expand All @@ -14,7 +14,7 @@

## Prerequisite 1: Xcode Command Line Tools

The Xcode Command Line Tools package includes utilities for compiling code from the terminal (gcc, make, etc.). This is needed for compiling mod files in NEURON.
The Xcode Command Line Tools package includes utilities for compiling code from the terminal. This is needed for compiling NEURON mod files during the hnn-core installation.

1. To install the package, type the following from a terminal.app window:

Expand All @@ -25,9 +25,7 @@ The Xcode Command Line Tools package includes utilities for compiling code from
- If you get the following error, you can skip this step.
`xcode-select: error: command line tools are already installed, use "Software Update" to install updates`

2. Then press `Install` in the pop-up dialog

<img src="install_pngs/xcode_tools.png" width="400" />
2. Then press `Install` in the pop-up dialog.

## Prerequisite 2: Miniconda (Python 3)

Expand All @@ -46,79 +44,64 @@ The Xcode Command Line Tools package includes utilities for compiling code from

```bash
conda env create -f environment.yml
conda install -y -n hnn openmpi mpi4py
```

2. Activate the HNN conda environment and install nlopt and NEURON

```bash
source activate hnn
pip install nlopt NEURON
```

3. Set the LD_LIBRARY_PATH for openmpi on conda activation. This environnement variable must be set before HNN can run simulations with openmpi. The variable is only useful inside the 'hnn' conda environment, so we will set the variable when conda is activated with `source activate hnn`. Run the following commands to make this automatic.

```bash
cd ${CONDA_PREFIX}
mkdir -p etc/conda/activate.d etc/conda/deactivate.d
echo "export OLD_LD_LIBRARY_PATH=\$LD_LIBRARY_PATH" >> etc/conda/activate.d/env_vars.sh
echo "export LD_LIBRARY_PATH=\$LD_LIBRARY_PATH:\${CONDA_PREFIX}/lib" >> etc/conda/activate.d/env_vars.sh
echo "export LD_LIBRARY_PATH=\$OLD_LD_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh
echo "unset OLD_LD_LIBRARY_PATH" >> etc/conda/deactivate.d/env_vars.sh
```

4. Open a new terminal window for the settings in the previous step to take effect and activate the HNN conda environment
2. Activate the HNN conda environment and python prerequisite packages

```bash
source activate hnn
conda activate hnn
pip install https://api.github.com/repos/jonescompneurolab/hnn-core/zipball/master
pip install nlopt
pip install mpi4py
```

## Run post-install checks

- Run the command below to check that all of the steps were successful and are ready to run HNN.

```bash
curl -s "https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/mac/check-post.sh" | bash
```
```bash
curl -s "https://raw.githubusercontent.com/jonescompneurolab/hnn/master/installer/mac/check-post.sh" | bash
```

## Download HNN source code

- The following commands will download the hnn source code and compile HNN's mod files for NEURON. We use the directory `hnn_source_code` for consistency with all of our instructions, but any directory can be used. You can use `git` if you prefer.

```bash
curl -OL https://github.com/jonescompneurolab/hnn/releases/latest/download/hnn.tar.gz
mkdir hnn_source_code
tar -x --strip-components 1 -f hnn.tar.gz -C hnn_source_code
cd hnn_source_code
make
```
```bash
git clone https://github.com/jonescompneurolab/hnn.git
cd hnn
```

## Run the HNN model

1. Start the HNN GUI from a terminal window:
1. Start the HNN GUI from a terminal window. Make sure the hnn environment has been activated each time a terminal window is opened:

```bash
source activate hnn
conda activate hnn
python hnn.py
```

2. 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.

3. When you run simulations for the first time, the following dialog boxes may pop-up and ask you for permission to allow connections through the firewall. Saying 'Deny' is fine since simulations will just run locally on your Mac.
3. When you run simulations for the first time, two dialog boxes may pop-up and ask you for permission to allow connections through the firewall. Saying 'Deny' is fine since simulations will just run locally on your Mac.

<img src="install_pngs/nrniv_firewall.png" width="400" />
4. You can now proceed to running the tutorials at [https://hnn.brown.edu/index.php/tutorials/](https://hnn.brown.edu/index.php/tutorials/) . Some things to note:

<img src="install_pngs/orterun_firewall.png" width="400" />

4. You can now proceed to running the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
- A directory called "hnn_out" exists in your home directory where the results from your simulations (data and param files) will be stored.

## Upgrading to a new version of HNN

HNN Releases can be seen on the [GitHub releases page](https://github.com/jonescompneurolab/hnn/releases/). You can also be notified of new releases by watching the hnn [repository on GitHub](https://github.com/jonescompneurolab/hnn/).
HNN Releases can be found on the [GitHub releases page](https://github.com/jonescompneurolab/hnn/releases/). You can also be notified of new releases by watching the hnn [repository on GitHub](https://github.com/jonescompneurolab/hnn/).

To download the latest HNN release:

If you downloaded the `tar.gz` file, simply re-run the steps above, but replace `hnn_source_code` with a new directory name.
```bash
curl -OL https://github.com/jonescompneurolab/hnn/releases/latest/download/hnn.tar.gz
mkdir hnn_source_code
tar -x --strip-components 1 -f hnn.tar.gz -C hnn_source_code
cd hnn_source_code
conda activate hnn
python3 hnn.py
```

Otherwise, if you are using `git`, then run `git pull origin master` from the source code directory.
If you are using `git`, then run `git pull origin master` from the source code directory.

## Troubleshooting

Expand Down
130 changes: 32 additions & 98 deletions installer/mac/check-post.sh
Original file line number Diff line number Diff line change
Expand Up @@ -28,34 +28,6 @@ echo "--------------------------------------"

CUR_DIR=$(pwd)

echo -n "Checking if HNN is compiled..."
if [[ -f ${CUR_DIR}/hnn.py ]]; then
if [[ -f "${CUR_DIR}/x86_64/hh2.mod" ]]; then
echo "ok"
if [[ "$VERBOSE" -eq "1" ]]; then
echo "HNN source code compiled and ready to use at ${CUR_DIR}"
echo
fi
else
echo "failed"
echo "Found a source code directory at ${CUR_DIR}, but it needs to be compiled (run make)."
echo
return=2
fi
else
if [[ -f "$HOME/hnn/x86_64/hh2.mod" ]]; then
echo "warning"
echo "Did you mean to run this from $HOME/hnn instead?"
echo
return=1
else
echo "failed"
echo "Didn't find HNN source code in this directory"
echo
return=2
fi
fi

echo -n "Checking for miniconda..."
MINICONDA_FOUND=
which conda > /dev/null 2>&1
Expand Down Expand Up @@ -161,24 +133,6 @@ else
echo "ok"
fi

MPI_WORKS=
if [[ "$MPI_FOUND" -eq "1" ]]; then
echo -n "Checking MPI functionality..."
COMMAND="mpiexec -n 1 echo \"hello\" 2>&1"
OUTPUT=$(mpiexec -n 1 echo "hello" 2>&1)
if [[ "$?" -eq "0" ]] && [[ "$OUTPUT" =~ "hello" ]]; then
echo "ok"
MPI_WORKS=1
else
echo "failed"
echo "the command that failed was:"
echo "$COMMAND"
echo $OUTPUT
echo
return=2
fi
fi

# NEURON functionality checks from https://github.com/jonescompneurolab/hnn/issues/11
NRNIV_WORKS=
if [[ "$NRN_FOUND" -eq "1" ]]; then
Expand All @@ -202,7 +156,7 @@ else
fi

PREREQS_INSTALLED=1
for prereq in "matplotlib" "scipy" "psutil" "numpy" "nlopt" "neuron"; do
for prereq in "matplotlib" "scipy" "psutil" "numpy" "nlopt" "neuron" "hnn_core"; do
echo -n "Checking Python can import $prereq module..."
$PYTHON -c "import $prereq" > /dev/null 2>&1
if [[ "$?" -eq "0" ]]; then
Expand Down Expand Up @@ -237,72 +191,52 @@ else
echo "Skipping NEURON funtionality tests with Python."
fi

echo -n "Checking for setting LD_LIBRARY_PATH..."
source ${CONDA_PREFIX}/etc/conda/activate.d/env_vars.sh > /dev/null 2>&1
if [[ "$?" -eq "0" ]] && [[ -n "${LD_LIBRARY_PATH}" ]]; then
echo "ok"
else
echo "warning"
echo "The LD_LIBRARY_PATH variable is not set correctly. Make sure you follow the installation"
echo "instructions to add the correct lines to ${CONDA_PREFIX}/etc/conda/activate.d/env_vars.sh"
return=1
fi


MPI_AND_NRNIV_WORKS=
if [[ "$NRN_FOUND" -eq "1" ]] && [[ "$NRNIV_WORKS" -eq "1" ]] && [[ "$MPI_WORKS" -eq "1" ]]; then
if [[ "$NRN_FOUND" -eq "1" ]] && [[ "$NRNIV_WORKS" -eq "1" ]]; then
echo -n "Checking NEURON nrniv funtionality with MPI..."
mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()' > /dev/null 2>&1
COMMAND="mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()'"
OUTPUT=$(export LD_LIBRARY_PATH=${CONDA_PREFIX}/lib; mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()')
if [[ "$?" -eq "0" ]]; then
echo "ok"
MPI_AND_NRNIV_WORKS=1
else
# try with LD_LIBRARY_PATH
COMMAND="mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()'"
OUTPUT=$(export LD_LIBRARY_PATH=${CONDA_PREFIX}/lib; mpiexec -n 2 nrniv -nobanner -nopython -mpi -c 'quit()')
if [[ "$?" -eq "0" ]]; then
echo "warning"
echo "The LD_LIBRARY_PATH variable is not set correctly. Make sure you follow the installation"
echo "instructions to add the correct lines to ${CONDA_PREFIX}/etc/conda/activate.d/env_vars.sh"
echo
return=1
MPI_AND_NRNIV_WORKS=1
else
echo "failed"
echo "Could not run nrniv with MPI"
echo "The command that failed was:"
echo "$COMMAND"
echo "Tried environment variable LD_LIBRARY_PATH=${CONDA_PREFIX}/lib"
echo "Command output (on a single line):"
echo $OUTPUT
echo
return=2
fi
echo "failed"
echo "Could not run nrniv with MPI"
echo "The command that failed was:"
echo "$COMMAND"
echo "Tried environment variable LD_LIBRARY_PATH=${CONDA_PREFIX}/lib"
echo "Command output (on a single line):"
echo $OUTPUT
echo
return=2
fi
else
echo "Skipping NEURON funtionality tests with MPI."
fi

NRNIV_AND_PYTHON_AND_MPI_WORKS=
if [[ "$NRN_FOUND" -eq "1" ]] && [[ "$NRNIV_WORKS" -eq "1" ]] &&
[[ "$PREREQS_INSTALLED" -eq "1" ]] && [[ "$MPI_WORKS" -eq "1" ]] &&
[[ "$PREREQS_INSTALLED" -eq "1" ]] &&
[[ "$MPI_AND_NRNIV_WORKS" -eq "1" ]]; then
echo -n "Checking NEURON nrniv funtionality with Python and MPI..."
COMMAND="mpiexec -n 2 nrniv -nobanner -mpi -python -c 'from neuron import h; pc = h.ParallelContext(); h.quit()' 2>&1"
OUTPUT=$(mpiexec -n 2 nrniv -nobanner -mpi -python -c 'from neuron import h; pc = h.ParallelContext(); h.quit()' 2>&1)
if [[ "$?" -eq "0" ]]; then
echo "ok"
NRNIV_AND_PYTHON_AND_MPI_WORKS=1
else
echo "failed"
echo "Could not run nrniv with Python and MPI"
echo "the command that failed was:"
echo "$COMMAND"
echo $OUTPUT
return=2
fi
echo -n "Checking NEURON nrniv funtionality with Python and MPI..."
COMMAND="mpiexec -n 2 nrniv -nobanner -mpi -python -c 'from neuron import h; pc = h.ParallelContext(); h.quit()' 2>&1"
OUTPUT=$(export LD_LIBRARY_PATH=${CONDA_PREFIX}/lib; mpiexec -n 2 nrniv -nobanner -mpi -python -c 'from neuron import h; pc = h.ParallelContext(); h.quit()' 2>&1)
if [[ "$?" -eq "0" ]]; then
echo "ok"
NRNIV_AND_PYTHON_AND_MPI_WORKS=1
else
echo "failed"
echo "Could not run nrniv with Python and MPI"
echo "the command that failed was:"
echo "$COMMAND"
echo "Tried environment variable LD_LIBRARY_PATH=${CONDA_PREFIX}/lib"
echo "Command output (on a single line):"
echo $OUTPUT
echo
return=2
fi
else
echo "Skipping NEURON funtionality tests with Python and MPI."
echo "Skipping NEURON funtionality tests with Python and MPI."
fi


Expand Down
3 changes: 1 addition & 2 deletions installer/mac/check-pre.sh
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,7 @@ if [ -n "$PYTHONPATH" ]; then
if [[ "$PYTHONPATH" =~ "NEURON" ]] || [[ "$PYTHONPATH" =~ "NRN" ]]; then
echo "warning"
echo "NEURON libraries found in PYTHONPATH variable. This was used before "
echo "the 'pip install' method. Make sure this matches the version used to "
echo "compile HNN modules with 'make'"
echo "the 'pip install' method."
echo "PYTHONPATH=$PYTHONPATH"
echo
return=1
Expand Down
Loading