<p align="center">
<img src="res/logo.png" width="200">
</p>
# A Simulation Execution Manager for ns-3 #
[](https://mybinder.org/v2/gh/signetlabdei/sem/develop?urlpath=lab)
This is a Python library to perform multiple ns-3 script executions, manage the
results and collect them in processing-friendly data structures.
# How does this work? #
For complete step-by-step usage and installation instructions, check out
[our documentation][docs].
# How to cite us #
If you used SEM for your ns-3 analysis, please cite the following paper, both to
provide a reference and help others find out about this tool:
Davide Magrin, Dizhi Zhou, and Michele Zorzi. 2019. A Simulation Execution
Manager for ns-3: Encouraging reproducibility and simplifying statistical
analysis of ns-3 simulations. In Proceedings of the 22nd International ACM
Conference on Modeling, Analysis and Simulation of Wireless and Mobile Systems
(MSWIM '19). ACM, New York, NY, USA, 121-125. DOI:
https://doi.org/10.1145/3345768.3355942
# Contributing #
This section contains information on how to contribute to the project. If you
are only interested in using SEM, check out the [documentation][docs].
If you want to contribute to sem development, first of all you'll need
an installation that allows you to modify the code, immediately see
the results and run tests.
## Building the module from scratch ##
This module is developed using
[`poetry`](https://python-poetry.org/docs/): in order to correctly
manage virtual environments and install dependencies, make sure it is installed.
Typically, the following is enough:
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
Note that, if poetry's installer does not add poetry's path to your shell's startup file properly, you may need to add
`source $HOME/.poetry/env` to your startup file. You can tell that you need to add it if your shell cannot find the poetry command the next time you open a terminal window.
Then, clone the repo (or your fork, by changing the url in the following
command), also getting the `ns-3` installations that are used for running
examples and tests:
```bash
git clone https://github.com/signetlabdei/sem
cd sem
git submodule update --init --recursive
```
From the project root, you can then install the package and the
requirements with the following:
```bash
poetry install
```
This will also get you a set of tools such as `sphinx`, `pygments` and `pytest`
that handle documentation and tests.
Finally, you can spawn a sub-shell using the new virtual environment by calling:
```bash
poetry shell
```
Now, you can start a python REPL to use the library interactively, issue the
bash `sem` program, run tests and compile the documentation of your local copy
of sem.
## Running tests ##
This project uses the [`pytest`](https://docs.pytest.org/en/latest/) framework
for running tests. Tests can be run, from the project root, using:
```bash
python -m pytest --doctest-glob='*.rst' docs/
python -m pytest -x -n 3 --doctest-modules --cov-report term --cov=sem/ ./tests
```
These two commands will run, respectively, all code contained in the `docs/`
folder and all tests, also measuring coverage and outputting it to the terminal.
Since we are mainly testing integration with ns-3, tests require frequent
copying and pasting of folders, ns-3 compilations and simulation running.
Furthermore, documentation tests run all the examples in the documentation to
make sure the output is as expected. Because of this, full tests are far from
instantaneous. Single test files can be targeted, to achieve faster execution
times, by substituting `./tests` in the second command with the path to the test
file that needs to be run.
## Building the documentation ##
Documentation can be built locally using the makefile's `docs` target:
```bash
make docs
```
## Running examples ##
The scripts in `examples/` can be directly run:
```bash
python examples/wifi_example.py
```
## Installing SEM in pip's editable mode ##
`pip` currently requires a `setup.py` file to install projects in editable mode.
As explained [here](https://github.com/python-poetry/poetry/issues/761), poetry
actually already generates a `setup.py`. After building the project, you can
extract the file from the archive using the following command:
``` bash
tar -xvf dist/*.tar.gz --wildcards --no-anchored '*/setup.py' --strip=1
```
After this step, it becomes possible to install SEM in editable mode.
## Authors ##
Davide Magrin
[docs]: https://signetlabdei.github.io/sem
Raw data
{
"_id": null,
"home_page": "https://github.com/signetlabdei/sem",
"name": "sem",
"maintainer": "",
"docs_url": null,
"requires_python": ">3.8,<4",
"maintainer_email": "",
"keywords": "ns-3,simulation,execution",
"author": "Davide Magrin",
"author_email": "magrinda@dei.unipd.it",
"download_url": "https://files.pythonhosted.org/packages/9d/3a/dcd75a9d00ee84c883202df3cd179ddb4be9776783e6960997c7acf0baec/sem-0.3.7.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"res/logo.png\" width=\"200\">\n</p>\n\n# A Simulation Execution Manager for ns-3 #\n\n[](https://mybinder.org/v2/gh/signetlabdei/sem/develop?urlpath=lab)\n\nThis is a Python library to perform multiple ns-3 script executions, manage the\nresults and collect them in processing-friendly data structures.\n\n# How does this work? #\n\nFor complete step-by-step usage and installation instructions, check out\n[our documentation][docs].\n\n# How to cite us #\n\nIf you used SEM for your ns-3 analysis, please cite the following paper, both to\nprovide a reference and help others find out about this tool:\n\nDavide Magrin, Dizhi Zhou, and Michele Zorzi. 2019. A Simulation Execution\nManager for ns-3: Encouraging reproducibility and simplifying statistical\nanalysis of ns-3 simulations. In Proceedings of the 22nd International ACM\nConference on Modeling, Analysis and Simulation of Wireless and Mobile Systems\n(MSWIM '19). ACM, New York, NY, USA, 121-125. DOI:\nhttps://doi.org/10.1145/3345768.3355942\n\n# Contributing #\n\nThis section contains information on how to contribute to the project. If you\nare only interested in using SEM, check out the [documentation][docs].\n\nIf you want to contribute to sem development, first of all you'll need\nan installation that allows you to modify the code, immediately see\nthe results and run tests.\n\n## Building the module from scratch ##\n\nThis module is developed using\n[`poetry`](https://python-poetry.org/docs/): in order to correctly\nmanage virtual environments and install dependencies, make sure it is installed.\nTypically, the following is enough:\n\n```bash\ncurl -sSL https://install.python-poetry.org | python3 -\n```\n\nNote that, if poetry's installer does not add poetry's path to your shell's startup file properly, you may need to add\n`source $HOME/.poetry/env` to your startup file. You can tell that you need to add it if your shell cannot find the poetry command the next time you open a terminal window.\n\nThen, clone the repo (or your fork, by changing the url in the following\ncommand), also getting the `ns-3` installations that are used for running\nexamples and tests:\n\n```bash\ngit clone https://github.com/signetlabdei/sem\ncd sem\ngit submodule update --init --recursive\n```\n\nFrom the project root, you can then install the package and the\nrequirements with the following:\n\n```bash\npoetry install\n```\n\nThis will also get you a set of tools such as `sphinx`, `pygments` and `pytest`\nthat handle documentation and tests.\n\nFinally, you can spawn a sub-shell using the new virtual environment by calling:\n\n```bash\npoetry shell\n```\n\nNow, you can start a python REPL to use the library interactively, issue the\nbash `sem` program, run tests and compile the documentation of your local copy\nof sem.\n\n## Running tests ##\n\nThis project uses the [`pytest`](https://docs.pytest.org/en/latest/) framework\nfor running tests. Tests can be run, from the project root, using:\n\n```bash\npython -m pytest --doctest-glob='*.rst' docs/\npython -m pytest -x -n 3 --doctest-modules --cov-report term --cov=sem/ ./tests\n```\n\nThese two commands will run, respectively, all code contained in the `docs/`\nfolder and all tests, also measuring coverage and outputting it to the terminal.\n\nSince we are mainly testing integration with ns-3, tests require frequent\ncopying and pasting of folders, ns-3 compilations and simulation running.\nFurthermore, documentation tests run all the examples in the documentation to\nmake sure the output is as expected. Because of this, full tests are far from\ninstantaneous. Single test files can be targeted, to achieve faster execution\ntimes, by substituting `./tests` in the second command with the path to the test\nfile that needs to be run.\n\n## Building the documentation ##\n\nDocumentation can be built locally using the makefile's `docs` target:\n\n```bash\nmake docs\n```\n\n## Running examples ##\n\nThe scripts in `examples/` can be directly run:\n\n```bash\npython examples/wifi_example.py\n```\n\n## Installing SEM in pip's editable mode ##\n\n`pip` currently requires a `setup.py` file to install projects in editable mode.\n\nAs explained [here](https://github.com/python-poetry/poetry/issues/761), poetry\nactually already generates a `setup.py`. After building the project, you can\nextract the file from the archive using the following command:\n\n``` bash\ntar -xvf dist/*.tar.gz --wildcards --no-anchored '*/setup.py' --strip=1\n```\n\nAfter this step, it becomes possible to install SEM in editable mode.\n\n\n## Authors ##\n\nDavide Magrin\n\n[docs]: https://signetlabdei.github.io/sem\n",
"bugtrack_url": null,
"license": "GPL-2.0-only",
"summary": "A Simulation Execution Manager for ns-3",
"version": "0.3.7",
"split_keywords": [
"ns-3",
"simulation",
"execution"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1ede2c75109b44f4f8cab9293da058406d29cbfd4b89e1a5c5b41278b859c3ea",
"md5": "0f5400adf8267ef12032c810ad008eba",
"sha256": "bbd1bcd3af201bc69dda69a6c027b3de2ae0085183d5ee0376b6158044e402f8"
},
"downloads": -1,
"filename": "sem-0.3.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f5400adf8267ef12032c810ad008eba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.8,<4",
"size": 43094,
"upload_time": "2023-01-30T11:52:06",
"upload_time_iso_8601": "2023-01-30T11:52:06.314608Z",
"url": "https://files.pythonhosted.org/packages/1e/de/2c75109b44f4f8cab9293da058406d29cbfd4b89e1a5c5b41278b859c3ea/sem-0.3.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9d3adcd75a9d00ee84c883202df3cd179ddb4be9776783e6960997c7acf0baec",
"md5": "f578bc64e945c00ff09ac0b481a4bc6d",
"sha256": "c28ccb13c51f06b413c59fd36af1b1d44918dbd2e2554d4ce642efbb6796abbb"
},
"downloads": -1,
"filename": "sem-0.3.7.tar.gz",
"has_sig": false,
"md5_digest": "f578bc64e945c00ff09ac0b481a4bc6d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.8,<4",
"size": 40966,
"upload_time": "2023-01-30T11:52:08",
"upload_time_iso_8601": "2023-01-30T11:52:08.333168Z",
"url": "https://files.pythonhosted.org/packages/9d/3a/dcd75a9d00ee84c883202df3cd179ddb4be9776783e6960997c7acf0baec/sem-0.3.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-30 11:52:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "signetlabdei",
"github_project": "sem",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sem"
}
JSON
