Python Library to implement Simulations, built on Crossbar.io and Django.
Project description
# Simpl Modelservice
Python Library to implement Simulations, built on Crossbar.io and Django.
[![Build Status](https://travis-ci.com/simplworld/simpl-modelservice.svg?token=cyqpBgqLC1o8qUptfcpE&branch=master)](https://travis-ci.com/simplworld/simpl-modelservice)
## Installation
$ pip install simpl-modelservice
## Setup development environment
$ git clone git@github.com:simplworld/simpl-modelservice.git
$ cd simpl-modelservice
$ mkvirtualenv simpl-modelservice
$ pip install -r dev-requirements.txt
$ pip install -e .
## Run tests
$ python runtests.py
## Development versioning
Install `bumpversion`:
$ pip install bumpversion
Then, to release a new version, increment the version number with:
$ bumpversion patch
Then push to the repo:
$ git push && git push --tags
## View current WAMP subscriptions and registrations
Point your browser to http://localhost:8080/monitor and open your javascript console
## How to run a modelservice as two separate processes
It's sometimes useful to run [crossbar](https://github.com/crossbario/crossbar/) and your own model code as separate processes. By default, `run_modelservice` runs crossbar configured to kick off the sub-process `run_guest`. You can change this by doing these 3 simple steps:
1. Get a copy of the currently in use crossbar configuration by running `./manage.py run_modelservice --print-config`. This will print the generated configuration file and then run normally. Simply cut-n-paste the configuration which will be a large JSON blob just before the usual Crossbar log messages.
2. Edit the configuration to remove the entire `{"type": "guest", ...}` stanza, saved to a file.
3. Run each piece separately. If we saved our configuration into `config.json` in the current directly this would look like:
./manage.py run_modelservice --config=./config.json --loglevel info --settings=simpl-calc.settings
for the crossbar service and then:
HOSTNAME=localhost PORT=8080 ./manage.py run_guest --settings=simpl-calc.settings
for the modelservice itself.
## Profiling
### Writing tasks
Profiling tasks are defined in `modelservice/profiles`.
The profiler will run any method that starts with `profile_` one or more times against a different number of workers.
Keep in mind that, unlike unit tests, profile tasks are not isolated.
#### Profile users
You can have workers that publish and call on WAMP as specific users. By using the `.call()` or `.publish()` method, it will call or publish as the user associated to that worker. To learn how to run workers associated to users, see [Running profile users](#running-profile-users).
#### Measuring
The `modelservice.utils.instruments` contains classes for measuring execution times. Check the module's docstrings for details.
#### Collecting results
You can collect the result of task by calling the `.publish_stat()` method:
```
async def profile_random(self):
with Timer() as timer:
some_value = random.random()
self.publish_stat('<unique stat name>', timer.elapsed, fmt='Average result was {stats.mean:.3f}')
```
The `fmt` string will receive an `instruments.StatAggregator` instance called `stats`. This object will collect the value from all workers that ran the task and will provide the following properties:
* `.min`: The lowest collected value
* `.max`: The highest collected value
* `.total`: The sum of the collected values
* `.count`: The number of collected values
Additionally, functions from the [`statistics` module](https://docs.python.org/3/library/statistics.html) are aliased as properties (ie: `.mean`, `.stdev`, etc.).
### Running the profiler anonymously
1. Run `simpl-games-api` and its modelservice
1. From any model, run its modelservice via `run_modelservice` or `run_guest`
1. From the same model directory, call `profile.sh`. You can use `profile.sh -h` for a list of options.
To run any model directory when logged into an AWS instance, call `aws_profile.sh`. You can use `aws_profile.sh -h` for a list of options.
#### Running profile users
You can have the profiler spawn workers as specific users by passing a file with their emails using the `-u` option.
Assuming you have a file called `myusers.txt` with the following content:
```text
s1@mysim.edu
s2@mysim.edu
s3@mysim.edu
```
You can then call:
```bash
$ profile.sh -u myusers.txt
```
And it will spawn 3 workers, each of one set up to `.call` and `.publish` as that one of those users.
To run from any model directory when logged into an AWS instance, call:
```bash
$ aws_profile.sh -u myusers.txt
```
Both `profile.sh` and `aws_profile.sh` invoke the `profile` management command.
#### Managing the Modelservice AWS Profiler instance
##### Django settings
* `PROFILER_AWS_KEY`: the AWS IAM access key
* `PROFILER_AWS_SEC`: the associated IAM secret key
##### Management commands
Management of the AWS profiler instance is performed by way of the `aws_profiler` management command.
###### status
```
:# ./manage.py aws_profiler --status
i-0733d74785931f857: stopped -- type: c5.18xlarge -- ip address: 18.216.171.181
```
###### start
```
:# ./manage.py aws_profiler --start
i-0733d74785931f857: pending -- type: c5.18xlarge -- ip address: 18.216.171.181
```
###### stop
```
:# ./manage.py aws_profiler --stop
i-0733d74785931f857: stopping -- type: c5.18xlarge -- ip address: 18.216.171.181
```
Copyright © 2018 The Wharton School, The University of Pennsylvania
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
Python Library to implement Simulations, built on Crossbar.io and Django.
[![Build Status](https://travis-ci.com/simplworld/simpl-modelservice.svg?token=cyqpBgqLC1o8qUptfcpE&branch=master)](https://travis-ci.com/simplworld/simpl-modelservice)
## Installation
$ pip install simpl-modelservice
## Setup development environment
$ git clone git@github.com:simplworld/simpl-modelservice.git
$ cd simpl-modelservice
$ mkvirtualenv simpl-modelservice
$ pip install -r dev-requirements.txt
$ pip install -e .
## Run tests
$ python runtests.py
## Development versioning
Install `bumpversion`:
$ pip install bumpversion
Then, to release a new version, increment the version number with:
$ bumpversion patch
Then push to the repo:
$ git push && git push --tags
## View current WAMP subscriptions and registrations
Point your browser to http://localhost:8080/monitor and open your javascript console
## How to run a modelservice as two separate processes
It's sometimes useful to run [crossbar](https://github.com/crossbario/crossbar/) and your own model code as separate processes. By default, `run_modelservice` runs crossbar configured to kick off the sub-process `run_guest`. You can change this by doing these 3 simple steps:
1. Get a copy of the currently in use crossbar configuration by running `./manage.py run_modelservice --print-config`. This will print the generated configuration file and then run normally. Simply cut-n-paste the configuration which will be a large JSON blob just before the usual Crossbar log messages.
2. Edit the configuration to remove the entire `{"type": "guest", ...}` stanza, saved to a file.
3. Run each piece separately. If we saved our configuration into `config.json` in the current directly this would look like:
./manage.py run_modelservice --config=./config.json --loglevel info --settings=simpl-calc.settings
for the crossbar service and then:
HOSTNAME=localhost PORT=8080 ./manage.py run_guest --settings=simpl-calc.settings
for the modelservice itself.
## Profiling
### Writing tasks
Profiling tasks are defined in `modelservice/profiles`.
The profiler will run any method that starts with `profile_` one or more times against a different number of workers.
Keep in mind that, unlike unit tests, profile tasks are not isolated.
#### Profile users
You can have workers that publish and call on WAMP as specific users. By using the `.call()` or `.publish()` method, it will call or publish as the user associated to that worker. To learn how to run workers associated to users, see [Running profile users](#running-profile-users).
#### Measuring
The `modelservice.utils.instruments` contains classes for measuring execution times. Check the module's docstrings for details.
#### Collecting results
You can collect the result of task by calling the `.publish_stat()` method:
```
async def profile_random(self):
with Timer() as timer:
some_value = random.random()
self.publish_stat('<unique stat name>', timer.elapsed, fmt='Average result was {stats.mean:.3f}')
```
The `fmt` string will receive an `instruments.StatAggregator` instance called `stats`. This object will collect the value from all workers that ran the task and will provide the following properties:
* `.min`: The lowest collected value
* `.max`: The highest collected value
* `.total`: The sum of the collected values
* `.count`: The number of collected values
Additionally, functions from the [`statistics` module](https://docs.python.org/3/library/statistics.html) are aliased as properties (ie: `.mean`, `.stdev`, etc.).
### Running the profiler anonymously
1. Run `simpl-games-api` and its modelservice
1. From any model, run its modelservice via `run_modelservice` or `run_guest`
1. From the same model directory, call `profile.sh`. You can use `profile.sh -h` for a list of options.
To run any model directory when logged into an AWS instance, call `aws_profile.sh`. You can use `aws_profile.sh -h` for a list of options.
#### Running profile users
You can have the profiler spawn workers as specific users by passing a file with their emails using the `-u` option.
Assuming you have a file called `myusers.txt` with the following content:
```text
s1@mysim.edu
s2@mysim.edu
s3@mysim.edu
```
You can then call:
```bash
$ profile.sh -u myusers.txt
```
And it will spawn 3 workers, each of one set up to `.call` and `.publish` as that one of those users.
To run from any model directory when logged into an AWS instance, call:
```bash
$ aws_profile.sh -u myusers.txt
```
Both `profile.sh` and `aws_profile.sh` invoke the `profile` management command.
#### Managing the Modelservice AWS Profiler instance
##### Django settings
* `PROFILER_AWS_KEY`: the AWS IAM access key
* `PROFILER_AWS_SEC`: the associated IAM secret key
##### Management commands
Management of the AWS profiler instance is performed by way of the `aws_profiler` management command.
###### status
```
:# ./manage.py aws_profiler --status
i-0733d74785931f857: stopped -- type: c5.18xlarge -- ip address: 18.216.171.181
```
###### start
```
:# ./manage.py aws_profiler --start
i-0733d74785931f857: pending -- type: c5.18xlarge -- ip address: 18.216.171.181
```
###### stop
```
:# ./manage.py aws_profiler --stop
i-0733d74785931f857: stopping -- type: c5.18xlarge -- ip address: 18.216.171.181
```
Copyright © 2018 The Wharton School, The University of Pennsylvania
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
simpl-modelservice-0.7.10.tar.gz
(138.4 kB
view hashes)
Built Distribution
Close
Hashes for simpl-modelservice-0.7.10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1f91b1ec00d31997e822e929ab5150885008b48350eb682303fc94750069c739 |
|
MD5 | c510455773b9f754fdbea7ff653ef8ba |
|
BLAKE2b-256 | 4758979aa37beec3876418c37fb9e095c401ddcf026c29ca641fd15880cbc5d4 |
Close
Hashes for simpl_modelservice-0.7.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2c95bfecf6d683a3357918165482170f2d0ac37ce0e6ec8dd4065f560d385262 |
|
MD5 | e647bb179abe45b7dab4a696fd4fd4aa |
|
BLAKE2b-256 | 695712c39b24fba713d82437be5916a601fd4adfaf531bc32d094e34ad3a5268 |