Merge pull request #5 from jgraeb/main

rename, update readme and documentation

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+ os: ubuntu-22.04
+ tools:
+ python: "3.12"
+
+mkdocs:
+ configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+ install:
+ - requirements: docs/requirements.txt

LICENSE.txt

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, California Institute of Technology
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,5 +1,11 @@
-# flowsynth
+# Floras: Flow-Based Reactive Test Synthesis for Autonomous Systems
 
-The flowsynth repository contains implementations of the algorithms developed in the following paper:
+<p align="center">
+ <img src="https://raw.githubusercontent.com/jgraeb/floras/refs/heads/main/docs/logo.png" width="250" />
+</p>
 
-[Josefine B. Graebener*, Apurva S. Badithela*, Denizalp Goktas, Wyatt Ubellacker, Eric V. Mazumdar, Aaron D. Ames, and Richard M. Murray. "Flow-Based Synthesis of Reactive Tests for Discrete Decision-Making Systems with Temporal Logic Specifications." ArXiv abs/2404.09888 (2024).](https://arxiv.org/abs/2404.09888)
+Floras documentation can be found [here](https://floras.readthedocs.io). For installation instructions, please visit [this page](https://floras.readthedocs.io/en/latest/contributing/).
+
+The floras repository contains implementations of the algorithms developed in the following paper:
+
+[Josefine B. Graebener*, Apurva S. Badithela*, Denizalp Goktas, Wyatt Ubellacker, Eric V. Mazumdar, Aaron D. Ames, and Richard M. Murray. "Flow-Based Synthesis of Reactive Tests for Discrete Decision-Making Systems with Temporal Logic Specifications." ArXiv abs/2404.09888 (2024).](https://arxiv.org/abs/2404.09888)

docs/automata.md

@@ -1 +1 @@
-::: flowsynth.components.automata
+::: floras.components.automata

docs/contributing.md

@@ -3,17 +3,22 @@
 If you want to modify FLORAS or contribute, you can also install it directly from source. We are using pdm to manage the dependencies.
 ```
 pip install pdm
-git clone url
+git clone https://github.com/tulip-control/flowsynth
 ```
 Navigate to the repo and run to install the FLORAS and all required dependencies:
 ```
 pdm install
 ```
-Next, enter the virtual environment created by pdm:
+Next, install spot by running
+```
+pdm run python get_spot.py
+```
+To enter the virtual environment created by pdm:
 ```
 $(pdm venv activate)
 ```
-New dependencies can be added by running:
+
+If you need to add dependencies you can do that by running:
 ```
 pdm add your_dependency_here
 ```

docs/index.md

@@ -1,6 +1,13 @@
 # FLORAS - Flow-based Reactive Test Synthesis for Autonomous Systems
 
+<figure markdown="span">
+ ![floras logo](logo.png "floras logo"){ width="300" }
+ <figcaption>Welcome to FLORAS!</figcaption>
+</figure>
+
 FLORAS is an open-source Python package for reactive test synthesis for autonomous systems using network flows.
 
+Installation instructions can be found [here](contributing.md).
+
 If you use FLORAS for research purposes, please acknowledge it by citing
 [Josefine B. Graebener\*, Apurva S. Badithela\*, Denizalp Goktas, Wyatt Ubellacker, Eric V. Mazumdar, Aaron D. Ames, and Richard M. Murray. "Flow-Based Synthesis of Reactive Tests for Discrete Decision-Making Systems with Temporal Logic Specifications." ArXiv abs/2404.09888 (2024).](https://arxiv.org/abs/2404.09888)

docs/installing.md

@@ -1,15 +1,10 @@
 # Installing FLORAS
 ### Requirements
-FLORAS requires `Python>=3.10` and a C++17-compliant compiler (for example `g++>=7.0` or `clang++>=5.0`).
+FLORAS requires `Python==3.10` and a C++17-compliant compiler (for example `g++>=7.0` or `clang++>=5.0`).
 You can check the versions by running `python --version` and `gcc --version`.
 
-### From Pypi
-FLORAS can be installed from Pypi as a standard Python package:
-```
-pip install floras
-```
 ### From Source
-If you want to modify FLORAS or contribute, you can also install it directly from source (see [here](contributing.md)).
+If you want to modify FLORAS or contribute, you can install it directly from source (see [here](contributing.md)).
 
 ### Troubleshooting
 Here are common errors we encountered and what we learned to fix the problem.

docs/optimization.md

@@ -1 +1 @@
-::: flowsynth.optimization.optimization
+::: floras.optimization.optimization

docs/product.md

@@ -1 +1 @@
-::: flowsynth.components.product
+::: floras.components.product

docs/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs-material
+mkdocstrings-python

docs/transition_system.md

@@ -1 +1 @@
-::: flowsynth.components.transition_system
+::: floras.components.transition_system

mkdocs.yml

@@ -23,6 +23,9 @@ plugins:
  python:
  paths: [src] # search packages in the src folder
 
+markdown_extensions:
+ - attr_list
+ - md_in_html
 
 copyright: >
  Copyright &copy; 2024 - <script>document.write(new Date().getFullYear())</script> Caltech

pyproject.toml

@@ -3,10 +3,10 @@ requires = ["pdm-backend"]
 build-backend = "pdm.backend"
 
 [project]
-name = "flowsynth"
+name = "floras"
 description = "A package for network flow-based test synthesis."
 authors = [
- {name = "flowsynth developers", email = "tbd"},
+ {name = "floras developers", email = "tbd"},
 ]
 license = {text = "BSD-3-Clause"}
 classifiers = [
@@ -30,10 +30,13 @@ dependencies = [
  "pytest>=8.3.3",
  "coverage>=7.6.1",
  "pygraphviz>=1.13",
+ "graphviz>=0.20.3",
 ]
-requires-python = ">=3.10"
+requires-python = "==3.10"
 version = "0.0.0"
 readme = "README.md"
 
 [project.scripts]
-from_json = "flowsynth.main:main"
+from_json = "floras.main:main"
+
+[tool.pdm]

src/flowsynth/components/automata.py → src/floras/components/automata.py

@@ -8,7 +8,7 @@
 from collections import OrderedDict as od
 import re
 import os
-from flowsynth.components.utils import powerset, neg, conjunction, disjunction
+from floras.components.utils import powerset, neg, conjunction, disjunction
 
 
 class Automaton:

src/flowsynth/components/product.py → src/floras/components/product.py

@@ -8,8 +8,8 @@
 import os
 import networkx as nx
 from itertools import product
-from flowsynth.components.transition_system import TranSys
-from flowsynth.components.automata import Automaton
+from floras.components.transition_system import TranSys
+from floras.components.automata import Automaton
 
 spot.setup(show_default='.tvb')
 

src/flowsynth/main.py → src/floras/main.py

@@ -2,11 +2,11 @@
 import ast
 import argparse
 
-from flowsynth.optimization.optimize import solve
-from flowsynth.components.automata import get_system_automaton, get_tester_automaton, get_product_automaton
-from flowsynth.components.transition_system import TranSys, TransitionSystemInput
-from flowsynth.components.product import sync_prod
-from flowsynth.components.utils import get_states_and_transitions_from_file
+from floras.optimization.optimize import solve
+from floras.components.automata import get_system_automaton, get_tester_automaton, get_product_automaton
+from floras.components.transition_system import TranSys, TransitionSystemInput
+from floras.components.product import sync_prod
+from floras.components.utils import get_states_and_transitions_from_file
 
 from ipdb import set_trace as st
 

src/flowsynth/optimization/optimization.py → src/floras/optimization/optimization.py

@@ -5,7 +5,7 @@
 import time
 import numpy as np
 import networkx as nx
-from flowsynth.optimization.utils import find_map_G_S
+from floras.optimization.utils import find_map_G_S
 from gurobipy import *
 from copy import deepcopy
 import os

src/flowsynth/optimization/optimize.py → src/floras/optimization/optimize.py

@@ -1,5 +1,5 @@
-from flowsynth.optimization.setup_graphs import setup_nodes_and_edges
-from flowsynth.optimization.optimization import MILP
+from floras.optimization.setup_graphs import setup_nodes_and_edges
+from floras.optimization.optimization import MILP
 
 from ipdb import set_trace as st