diff --git a/README.md b/README.md index 1f1406b..0e71830 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,107 @@ # nest in situ vis - *nest in situ vis* is Copyright (c) 2017 RWTH Aachen University, Germany, Virtual Reality & Immersive Visualization Group. +## Overview + +*nest in situ vis* (`niv`) is (the yet prototypical implementation of) a library facilitating in situ visualization for the [nest simulator](http://www.nest-simulator.org). + +With `niv` data can be collected in nest's recording backends and transported to a visualization process. Currently, only on-node transport to a separate visualization process is provided using shared memory. + + +## Building + + +### Requirements + +* a customized nest simulator with nestio and a conduit recording backend +* [conduit 0.2.1](https://github.com/LLNL/conduit/tree/v0.2.1) +* Boost python and boost interprocess v1.64.0 +* Python 2.7.13 +* CMake 3.8.2 (or above) +* gcc 5.3 (or above) + + +### Compiling the Library + +* In a teminal, `cd to `niv`'s root directory + +``` +mkdir build +cd build +cmake .. \ + -DCONDUIT_DIR= \ + -DBOOST_ROOT= \ + -DPYTHON_INCLUDE_DIR= \ + -DPYTHON_LIBRARY= +make +``` + +### Compiling the Custom Nest Simulator + +These are hints for compiling nest (not included in this repository). + +* In a terminal, `cd` to nest's root directory + +``` +mkdir build +cd build +cmake ../.. \ + -Dwith-conduit= \ + -Dniv_DIR= \ + -DPYTHON_INCLUDE_DIR= \ + -DPYTHON_LIBRARY= \ + -DCMAKE_INSTALL_PREFIX:PATH= +make +make install +``` + + +### Generating the Demo Runners + +* In a teminal, `cd to `niv`'s root directory + +``` +cd build +cmake . -DNEST_DIR= +chmod +x chmod +x demo/nest_python_vis/*.sh +``` + + +## Running the Demo + +You'll need two terminals. + +* in both, `cd` to `/demo/nest_python_vis` + +* in the first + +``` +./run_vis.sh +``` + +* in the second + +``` +./run_sim.sh +``` + +* in the visualization app press "Start" +* in the simulation app press "nest.Simulate(20)" + + +## Releasing Shared Memory if Something Breaks + +If one of the two apps crashes, shared memory might still exist. Consequently, the visualization will throw an exception. In order to manually release the shared memory: + +* in a terminal `cd` to `niv`s build directory + +``` +niv/helper_apps/niv-shared-memory destroy +``` + ## License Licensed under the Apache License, Version 2.0 (the "License"); @@ -18,3 +115,8 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. + + +## Acknowledgements + +`niv` is developed in the Human Brain Project. This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 720270 (HBP SGA1).