rasaeco 0.0.15

Single-File Release

Please download and unzip the latest release from the GitHub release page.

From PyPI

The tool is also available on PyPI.

Create a virtual environment:

python -m venv venv-rasaeco

Activate it (in Windows):

venv-rasaeco\Scripts\activate

or in Linux:

source venv-rasaeco/bin/activate

Install the tool in the virtual environment:

pip3 install rasaeco

Render once

Render the scenarios in-place once:

pyrasaeco-render.exe once --scenarios_dir c:\some\path\to\scenarios

(Change c:\some\path\to\scenarios to fit your system.)

Open the scenario ontology with your browser from: c:\some\path\to\scenarios\ontology.html.

(Don’t forget to change c:\some\path\to\scenarios again to fit your system.)

Render continuously

Monitor the scenario files and re-render on changes:

pyrasaeco-render.exe continuously --scenarios_dir c:\some\path\to\scenarios

(Change c:\some\path\to\scenarios to fit your system.)

Open the scenario ontology with your browser from: c:\some\path\to\scenarios\ontology.html.

(Don’t forget to change c:\some\path\to\scenarios again to fit your system.)

Render continuously + automatic refresh

pyrasaeco-render can also start a demo server for you so that you do not have to manually re-load in the browser. You have to specify the port and the server will be automatically started:

pyrasaeco-render.exe continuously
    --scenarios_dir c:\some\path\to\scenarios
    --port 8000

(Change c:\some\path\to\scenarios to fit your system.)

The ontology will be available on: http://localhost:8000.

Help

pyrasaeco-render.exe -h
pyrasaeco-render.exe once -h
pyrasaeco-render.exe continuously -h

Directory Structure

Write documents in the following directory structure:

ontology/
    some-scenario/
        scenario.md
    some-group/
        another-scenario/
            scenario.md
        yet-another-scenario/
            scenario.md
...

The identifier of a scenarios is given by the POSIX path of the scenario directory relative to the ontology directory.

For example, some-scenario and some-group/another-scenario.

Header

Write a <rasaeco-meta> header at the beginning of a scenario.

Here is an example:

<rasaeco-meta>
{
    "title": "Some Scenario",
    "contact": "Marko Ristin <rist@zhaw.ch>, Somebody Else <somebody@else.ch>",
    "relations": [
        { "target": "some-group/another_scenario", "nature": "is instance of" }
        { "target": "some-group/yet_another_scenario", "nature": "refines" }
    ],
    "volumetric": [
        {
            "aspect_from": "as-planned", "aspect_to": "safety",
            "phase_from": "construction", "phase_to": "construction",
            "level_from": "site", "level_to": "site"
        }
    ]
}
</rasaeco-meta>

Tags in the Scenario

Tag text in markdown with XML tags.

Models. Models are defined as <model name="...">...</model>.

Model references are written using <modelref> tag:

The possible placements for the reception platform should be computed based on
the <modelref name="observed/main" />.

It is also possible to reference models from another scenario by writing the scenario identifier, followed by # and the model name:

This is a dummy reference to the model <modelref name="scaffolding#plan/main" />.

Definitions. Definitions are defined <def name="...">...</def>.

If you want to write (pseudo)code in the definition, use ``` (three backticks):

<def name="reception_platform">

```bim
reception_platform
    is IfcBuildingElementType modeled in observed/main
    with .ElementType == "ReceptionPlatform"
```

</def>

In general, give the name using singular form, snake_case and lower-case. For example, reception_platform.

Definition references are written using <ref> tag:

The <ref name="reception_platform" /> can not be appropriately fixed.

It is also possible to reference models from another scenario by writing the scenario identifier, followed by # and the definition name:

This is a dummy reference to the definition <ref name="scaffolding#scaffold" />.

We apply a couple of text transformations during rendering to improve the readability. The underscores in the references are replaced with spaces. If the reference is followed by an “s”, it will be automatically inflected to a plural.

For example,

The <ref name="misplaced_scaffold" />s are ...

will be rendered to:

The misplaced scaffolds are ...

Marking phase and level. Use <phase> and <level> to mark the phase in the building life cycle and hierarchy level of detail, respectively.

<phase name="planning">During the planning phase, the <ref name="scaffolds" />
are wrongly planed.</phase>

<phase name="construction">The <ref name="receptionPlatforms" /> can not be appropriately fixed
on <level name="site">the site</level>.</phase>

Test cases. Test cases are marked using <test name="...">...</test>. You can reference the individual tests using <testref name="..." />.

Analogous to <ref> and <modelref>, references to test cases extend across scenarios.

Acceptance criteria. Acceptance criteria are marked using <acceptance name="...">...</test>. You can reference the individual acceptance criteria using <acceptanceref name="..." />.

Analogous to <ref> and <modelref>, references to acceptance criteria extend across scenarios.

References to a scenario as a whole. You can reference a scenario from another scenario using <scenarioref name="..." />.

Further Examples

Please see Sample scenarios for further examples.