Skip to content

Update README.md #63

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.

Sign up for GitHub

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

Open
hwauck wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README.md #63

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
80 changes: 11 additions & 69 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,12 @@ The `funman` package performs Functional Model Analysis by processing a request

# Quickstart

This section explains how to run `funman`, and the following section describes the analysis request in more detail.
This section explains how to run `funman`, and the following section describes the analysis request in more detail. The following are required for `funman` to run:
- docker
- python3
- The python 'requests' package

We recommend using a pre-built docker image to run or develop the `funman` source, due to a few build dependencies. To run `funman` via its API, (in the `funman` root directory) start the API with the script:
We recommend using a pre-built docker image to run or develop the `funman` source, due to a few build dependencies. To run `funman` via its API, (in the `funman` root directory) start the API with the script:

```bash
sh terarium/scripts/run-api-in-docker.sh
Expand All @@ -34,59 +37,23 @@ sh terarium/scripts/run-api-in-docker.sh
This will pull the latest release of the `funman` API image and start a new container. Then, to submit analysis requests to the API, run the following script:

```bash
terarium/run_example.sh petrinet-sir
terarium/run_example.sh sir
```

This script will run a request, as specified in `resources/terarium-tests.json`.

Running the example will POST a model analysis request, wait, and then GET the results. `funman` analysis runs in an anytime fashion, and the GET request may return only partial results. The example will generate the following output:

```
Running example 'petrinet-sir':
{
"name": "petrinet-sir",
"model-path": "amr/petrinet/terrarium-tests/sir.json",
"request-path": "amr/petrinet/terrarium-tests/sir_request.json"
}
################################################################################
################################################################################
Making POST request to http://127.0.0.1:8190/api/queries with contents:
~/repositories/funman/terarium ~/repositories/funman
{
"model": <Contents of /home/danbryce/funman/resources/amr/petrinet/terrarium-tests/sir.json>
"request": <Contents of /home/danbryce/funman/resources/amr/petrinet/terrarium-tests/sir_request.json>
}
################################################################################
################################################################################
Response for query:
{
"id": "cfabd91c-4a6a-42aa-8d10-e88b4ca2dd5f",
"model": "Removed for brevity",
"request": "Removed for brevity"
}
################################################################################
################################################################################
Work Id is 'cfabd91c-4a6a-42aa-8d10-e88b4ca2dd5f'
Waiting for 5 seconds...
################################################################################
################################################################################
Making GET request to http://127.0.0.1:8190/api/queries/cfabd91c-4a6a-42aa-8d10-e88b4ca2dd5f:
{
"id": "cfabd91c-4a6a-42aa-8d10-e88b4ca2dd5f",
"model": "Removed for brevity",
"progress": {
"progress": 0.6918088739568541,
"coverage_of_search_space": 0.6918088739568541
},
"request": "Removed for brevity",
"parameter_space": {
"num_dimensions": 6,
"true_boxes": [ {"Removed for brevity"}, {"Removed for brevity"}, ...]
"false_boxes": [ {"Removed for brevity"}, {"Removed for brevity"}, ...]
}
}
~/repositories/funman
```

The response is the status of the query, which includes the model and request used in the query, as well as progress and the current parameter space.
The response is the status of the query, which includes the model and request used in the query, as well as progress and the current parameter space.

# Quickstart Example Description

Expand Down Expand Up @@ -118,7 +85,7 @@ Solving this analysis problem generates a parameter space, as summarized by the

The plot illustrates the parameter space as a matrix of 2D plots for each pair of parameters. (This example includes parameters $S0$, $I0$, and $R0$ for the initial state assignment). `funman` introduces the `timestep` as an additional parameter to support reasoning about different time spans. This `timestep` is important for many scenarios because the constraints may be satsified or not under different assumptions about the scenario time span.

The upper left plot for $\beta$-$\gamma$ projects all boxes onto $\beta$ and $\gamma$, indicating that there are values of the other parameters where any assignment to the pair will satisfy the constraint. Unsurprisingly, larger values for $\beta$ and smaller values for $\gamma$ result in more scenario time spans where the constraints are satisfied (darker green regions include more true regions that are stacked/projected onto $\beta$ and $\gamma$).
The upper left plot for $\beta-\gamma$ projects all boxes onto $\beta$ and $\gamma$, indicating that there are values of the other parameters where any assignment to the pair will satisfy the constraint. Unsurprisingly, larger values for $\beta$ and smaller values for $\gamma$ result in more scenario time spans where the constraints are satisfied (darker green regions include more true regions that are stacked/projected onto $\beta$ and $\gamma$).

The lower left plots for $\beta$-timestep and $\gamma$-timestep help to interpret the $\beta$-$\gamma$ plot. Timesteps 5-10 (corresponding to 50-100 days) include several false regions (also stacked) where the constraints are not satisfied, and a few true regions where they are satisfied.

Expand Down Expand Up @@ -295,6 +262,7 @@ The documentation at [https://siftech.github.io/funman/use_cases.html](https://s
- .pylintrc: pylint config
- LICENSE
- Makefile
- Makefile.prev
- Makefile.uncharted: Uncharted's custom make
- README.md
- pyproject.toml: project configuration
Expand All @@ -303,32 +271,6 @@ The documentation at [https://siftech.github.io/funman/use_cases.html](https://s
- setup.py: pip install configuration


### Pre-commit hooks
`funman` has a set of pre-commit hooks to help with code uniformity. These hooks
will share the same rules as any automated testing so it is recommended to
install the hooks locally to ease the development process.

To use the pre-commit hooks you with need the tools listed in
`requirements-dev.txt`. These should be installed in the same environment where
you git tooling operates.
```bash
pip install -r requirements-dev.txt
```

Once install you should be able to run the following from the root of the repo:
```bash
make install-pre-commit-hooks
```

Once installed you should begin to receive isort/black feedback when
committing. These should not alter the code during a commit but instead just
fail and prevent a commit if the code does not conform to the specification.

To autoformat the entire repo you can use:
```bash
make format
```

### Code coverage
Pytest is configured to generate code coverage, and requires the `pytest-cov`
package to be installed. The `pytest-cov` package is included in the
Expand Down