You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# building a wheel out of tree simply doesn't work, without warning. Copy the package tree in a temporary location and build there (cwd must also be on location of setup.py or the files won't be added)
# building tow wheels at once can't happen in the same folder. break them into separarte directories like in: https://stackoverflow.com/questions/51300874/how-do-i-build-multiple-wheel-files-from-a-single-setup-py
237
+
238
+
# TODO improve verification for auditwheel and delocate, when the authors add such an option
239
+
240
+
# haven't found out yet how to mix static patterns with per-target variables yet
Copy file name to clipboardExpand all lines: README.md
+57-27Lines changed: 57 additions & 27 deletions
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,15 @@ This software is released as open-source, under the GPL v3 licence. Refer to LIC
9
9
10
10
11
11
## Quickstart
12
+
13
+
The easiest way to get started is to get the Python package: `pip install eden-simiulator`
14
+
and then invoke EDEN from Python:
15
+
```python
16
+
from eden_simulator import runEden
17
+
sim_results = runEden('<LEMS simulation file>.xml') # replace filename with your own
18
+
```
19
+
20
+
For a demo run of NeuroML networks and performance comparison with NEURON:
12
21
A Jupyter environment with EDEN and associated tooling pre-installed is available at https://github.com/spanag/eden-sim-jupyter-demo .
13
22
Just click the Binder link on that page and you can use EDEN as shown on the bundled Python notebook.
14
23
@@ -37,33 +46,10 @@ On Linux setups, GCC is commonly installed; if it is not, refer to your distribu
37
46
38
47
In all cases, make sure that the compiler targets the same architecture as the executable, see also [Usage](#usage) for more details.
39
48
40
-
### Building from source
41
-
The following software packages are required to build the source code:
42
-
-`gcc` compiler, or alternatively the `icc` compiler. Specifically, a compiler version that supports C++14.
43
-
-`flex` version 2.6 or later
44
-
-`bison` version 3.0 or later
45
-
46
-
On Linux, most other tools for building are pre-installed or they can be easily installed; consult your distribution's reference on installing essential build tools.
47
-
48
-
For building on Windows, batch scripts are available on the [testing/windows](testing/windows) directory for installing all the necessary build tools and libraries, setting the shell's PATH to use them and building the standalone executable or Python wheel, all without affecting the system or user setup.
49
-
50
-
For building on macOS, shell scripts are available on the [testing/mac](testing/mac) directory for installing all the necessary build tools and libraries, setting the shell's PATH to use them and building the standalone executable or Python wheel.
51
-
*Note* The `testing/mac/download-setup-requirements.bash` script installs Command Line Developer Tools for Mac, Homebrew and various Homebrew packages in the system, in the process installing the required tooling.
52
-
53
-
Use environment variable `BUILD=release` or `BUILD=debug` to run a production or debugging build of the program executable, respectively. The executable will be available on `bin/eden.<build>.<compiler>.cpu.x` (`.exe` on Windows)
54
-
55
-
If the NeuroML Python package `pyNeuroML` is installed, a Python wrapper for the local build of EDEN, `eden_tools`, can also be installed - run `pip` on directory `testing/python_package` . EDEN should then be on `PATH` to be invoked by the Python package.
56
-
57
-
If MPI is also installed, a MPI-enabled version of EDEN (with hybrid MPI/OpenMP parallelization) can be built, by running `make` with the `USE_MPI` flag. This configuration has been tested with standard MPICH on Linux; consult your HPC cluster's documentation for specific details on the MPI build process.
58
-
59
-
### Docker images
60
-
Alternatively, Docker images with EDEN and an assortment of tools are available and can also be built, for containerized environments. The Dockerfiles are available on the `testing/docker` folder, and they can be built in the proper order through the Makefile in the folder.
61
-
The Dockerfiles are at the moment available for Linux; support for other platforms is pending.
62
-
63
-
If Docker is installed and accessible to the user, an automated testing suite can also be run to verify EDEN's results against the NEURON simulator's for deterministic models. Run `make test` to run the automated tests.
64
-
65
49
66
50
## Usage
51
+
52
+
### From the command line
67
53
EDEN directly runs NeuroML models of neural networks. (For more information about the NeuroML model format, refer to http://neuroml.org )
68
54
It can be run from the command line, with the following command referencing the LEMS simulation file of the NeuroML model to be run:
69
55
```
@@ -79,15 +65,21 @@ Some `.gen.c` and `.gen.so` temporary files may also be generated, these can be
79
65
80
66
Per-thread parallelism can be adjusted through the `OMP_NUM_THREADS` environment variable.
81
67
82
-
Alternatively to the command line, the simulator can also be run within a Python program, if the standalone `eden_simulator` Python package (or the equivalent wrapper-only `eden_tools` package) is installed.
68
+
### From Python
69
+
Alternatively to the command line, the simulator can also be run within a Python program, if the `eden_simulator` Python package is installed.
results = eden_simulator.runEden('<LEMS simulation file>.xml')# replace filename with your own
87
74
```
88
75
This interface returns the recorded trajectories specified in the simulation files in a Python dictionary, same as pyNeuroML does with other simulation backends.
76
+
89
77
Thread-level parallelism can also be controlled with the `threads` optional argument.
90
78
79
+
If other command-line arguments should be added, they can be specified as a list of strings in the optional parameter `extra_cmdline_args`.
80
+
In case a specific instance of the EDEN executable is preferred, it can be selected with the optional parameter `executable_path`.
81
+
Both options can be combined into a fully custom command to be run from Python: it can be passed as a list of strings in the optional parameter `full_cmdline`.
82
+
91
83
### Setting `PATH` to include a compiler
92
84
93
85
When running EDEN, make sure that the selected compiler (`gcc` by default) is available on PATH and has the same bitness and architecture as the build of EDEN in use. This is a concern on Windows (where both 32 and 64 bit programs are common) and on certain HPC clusters where the login and job nodes may run different instruction sets.
The following software packages are required to build the source code:
105
+
-`gcc` compiler, or alternatively the `icc` compiler. Specifically, a compiler version that supports C++14.
106
+
-`flex` version 2.6 or later
107
+
-`bison` version 3.0 or later
108
+
109
+
On Linux, most other tools for building are pre-installed or they can be easily installed; consult your distribution's reference on installing essential build tools.
110
+
111
+
For building on Windows, batch scripts are available on the [testing/windows](testing/windows) directory for installing all the necessary build tools and libraries, setting the shell's PATH to use them and building the standalone executable or Python wheel, all without affecting the system or user setup.
112
+
113
+
For building on macOS, shell scripts are available on the [testing/mac](testing/mac) directory for installing all the necessary build tools and libraries, setting the shell's PATH to use them and building the standalone executable or Python wheel.
114
+
*Note* The `testing/mac/download-setup-requirements.bash` script installs Command Line Developer Tools for Mac, Homebrew and various Homebrew packages in the system, in the process installing the required tooling.
115
+
*Note 2* The Apple developer tools are not suitable to build EDEN, because they lack OpenMP support which is required by EDEN. Instead, we recommend the developer tools installed by `download-setup-requirements.bash`.
116
+
117
+
Before attempting to build manually, source the `setpath` script for the platform you are building against so that the necessary tools are on PATH. (See platform-spacific instructions above.)
118
+
119
+
Use environment variable `BUILD=release` or `BUILD=debug` to run a production or debugging build of the program executable, respectively. The executable will be available on `bin/eden.<build>.<compiler>.cpu.x` (`.exe` on Windows)
120
+
121
+
### Building Python wheels
122
+
Beside the program itself, EDEN can also be built as a Python package, which offers more integrated interface to the program. The python package is created in the installable `.whl` (wheel) format.
123
+
124
+
There are two options to build a Python wheel:
125
+
- The first is as a standalone wheel containing the EDEN executable (hence the wheel is specific to one OS and processor type). This is the type of wheels avcailable through `pip install`.
126
+
- The second option is as a 'hollow' wheel which works everywhere, but relies on EDEN already being available on PATH through different means. This type is useful in classes where a special (e.g. custom-built) version of EDEN is preferred to the generic version of 'standalone' wheels.
127
+
128
+
Both types of wheel can be built as the respective targets `wheel` and `hollow_wheel` of the Makefile. The resulting `.whl` files are located in the paths `testing/sandbox/{wheel, wheel_hollow}/dist`.
129
+
130
+
### Building for MPI
131
+
If MPI is also installed, a MPI-enabled version of EDEN (with hybrid MPI/OpenMP parallelization) can be built, by running `make` with the `USE_MPI` flag. This configuration has been tested with standard MPICH on Linux; consult your HPC cluster's documentation for specific details on the process for MPI-enabled builds.
132
+
133
+
## Docker images
134
+
Alternatively, Docker images with EDEN and an assortment of tools are available and can also be built, for containerized environments. The Dockerfiles are available on the `testing/docker` folder, and they can be built in the proper order through the Makefile in the folder.
135
+
The Docker images are Linux-native but they can as well run on Windows and MacOS through [Docker Desktop](https://www.docker.com/products/docker-desktop/).
136
+
137
+
If Docker is installed and accessible to the user, an automated testing suite can also be run to verify EDEN's results against the NEURON simulator's for deterministic models. Run `make test` to run the automated tests.
138
+
139
+
110
140
## Dockerfile
111
141
112
142
A demonstration-ready Docker image is available, using the Dockerfile on this top-level directory.
0 commit comments