diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8c861c34..c88bd1ae 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -28,7 +28,7 @@ jobs: - run: pip install pdoc # ADJUST THIS: build your documentation into docs/. # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here. - - run: pdoc macq --math -o docs + - run: pdoc macq --math --docformat google -o docs - uses: actions/upload-pages-artifact@v3 with: diff --git a/README.md b/README.md index dc264b79..4b9d49f2 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ This library is a collection of tools for planning-like action model acquisition from state trace data. It contains a reimplementation from many existing works, and generalizes some of them to new settings. -## Usage +## Example Usage ```python from macq import generate, extract @@ -21,11 +21,11 @@ traces.generate_more(10) action = traces[0][0].action traces.get_usage(action) -[0.05, 0.05, ..., 0.05] +# [0.05, 0.05, ..., 0.05] trace = traces[0] len(trace) -20 +# 20 trace.fluents trace.actions @@ -38,7 +38,7 @@ trace.get_total_cost() You can find the full scope of papers considered in the survey (implemented and otherwise) at http://macq.planning.domains . This repository of model acquisition techniques will be added to over time. -## Survey Papers +## Related Survey Papers - [A Review of Machine Learning for Automated Planning](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.231.4901&rep=rep1&type=pdf) (see Fig 2) - [A Review of Learning Planning Action Models](https://hal.archives-ouvertes.fr/hal-02010536/document) (see Tbl 3) diff --git a/docs/extract/amdn.md b/docs/extract/amdn.md index e464e4da..89ca3d2b 100644 --- a/docs/extract/amdn.md +++ b/docs/extract/amdn.md @@ -1,15 +1,3 @@ -# AMDN +### AMDN -## Usage - -```python -from macq import generate, extract - -print(model.details()) -``` - -**Output:** - -```text - -``` +Coming soon... diff --git a/docs/extract/arms.md b/docs/extract/arms.md index 44b5ae9b..0e3da2f1 100644 --- a/docs/extract/arms.md +++ b/docs/extract/arms.md @@ -1,6 +1,6 @@ -# ARMS +### ARMS -## Usage +#### Usage ```python from macq import generate, extract diff --git a/docs/extract/extract.md b/docs/extract/extract.md index 883919c6..6d3e6a36 100644 --- a/docs/extract/extract.md +++ b/docs/extract/extract.md @@ -9,7 +9,7 @@ Include the argument `debug=True` to `Extract` to enable debugging for any extraction technique. -_Note: debugging output and interfaces are unique to each method._ +**Note**: debugging output and interfaces are unique to each method. ## Extraction Techniques @@ -19,23 +19,25 @@ _Note: debugging output and interfaces are unique to each method._ - [AMDN](#amdn) - [LOCM](#locm) -.. include:: ../../../docs/templates/extract/observer.md +---- + +.. include:: ../../docs/extract/observer.md --- -.. include:: ../../../docs/templates/extract/slaf.md +.. include:: ../../docs/extract/slaf.md --- -.. include:: ../../../docs/templates/extract/arms.md +.. include:: ../../docs/extract/arms.md --- -.. include:: ../../../docs/templates/extract/amdn.md +.. include:: ../../docs/extract/amdn.md --- -.. include:: ../../../docs/templates/extract/locm.md +.. include:: ../../docs/extract/locm.md --- diff --git a/docs/extract/locm.md b/docs/extract/locm.md index 19b2fcc9..2e76db1f 100644 --- a/docs/extract/locm.md +++ b/docs/extract/locm.md @@ -1 +1,3 @@ -# LOCM +### LOCM + +Coming soon... diff --git a/docs/extract/observer.md b/docs/extract/observer.md index 38d35b06..e08f1c84 100644 --- a/docs/extract/observer.md +++ b/docs/extract/observer.md @@ -1,6 +1,6 @@ -# Observer +### Observer -## Usage +#### Usage ```python from macq import generate, extract diff --git a/docs/extract/slaf.md b/docs/extract/slaf.md index dc616b74..abca2c87 100644 --- a/docs/extract/slaf.md +++ b/docs/extract/slaf.md @@ -1,6 +1,6 @@ -# SLAF +### SLAF -## Usage +#### Usage ```python from macq import generate, extract diff --git a/docs/index.md b/docs/index.md index b3d64359..9733d0f2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,37 @@ -# Usage Documentation +# General API ## Trace Generation -- [VanillaSampling](macq/generate/pddl.html#VanillaSampling) -- [RandomGoalSampling](macq/generate/pddl.html#RandomGoalSampling) -- [FDRandomWalkSampling](macq/generate/pddl.html#FDRandomWalkSampling) +These are the various methods implemented to generate the base trace data. + +| Algorithm | Description | +|---|---| +| [VanillaSampling](macq/generate/pddl.html#VanillaSampling) | Samples actions uniformly at random | +| [RandomGoalSampling](macq/generate/pddl.html#RandomGoalSampling) | Samples goals by taking a random subset of a state reached after a random walk | +| [FDRandomWalkSampling](macq/generate/pddl.html#FDRandomWalkSampling) | Random walk based on a heuristic-driven depth calculation (algorithm introduced in the [FD planning system](https://www.fast-downward.org/)) | +| [TraceFromGoal](macq/generate/pddl.html#TraceFromGoal) | Generates a trace from a given domain/problem (with a goal state) | +| [CSV](macq/generate/csv.html) | Reads a CSV file to generate a trace | ## Tokenization -- [IdentityObservation](macq/observation.html#IdentityObservation) -- [AtomicPartialObservation](macq/observation.html#AtomicPartialObservation) +Once trace data is loaded, you can process the traces to produce lists of observations. The methods range from the identity observation (constaining the same data as original traces) to noisy and/or partially observable observations. + +| Algorithm | Description | +|---|---| +| [IdentityObservation](macq/observation.html#IdentityObservation) | Unmodified versions of the input traces | +| [PartialObservation](macq/observation.html#PartialObservation) | Observations with a subset of the fluents hidden in the states | +| [AtomicPartialObservation](macq/observation.html#AtomicPartialObservation) | Similar to `PartialObservation`, except everything is stored as atomic strings (not fluents and parameters) | +| [ActionObservation](macq/observation.html#ActionObservation) | Observations with only the actions listed (i.e., states discarded) | +| [NoisyObservation](macq/observation.html#NoisyObservation) | Observations with added noise to the fluents | +| [NoisyPartialObservation](macq/observation.html#NoisyPartialObservation) | Observations with added noise to the fluents and a subset of the fluents hidden in the states | +| [NoisyPartialDisorderedParallelObservation](macq/observation.html#NoisyPartialDisorderedParallelObservation) | Observations with added noise to the fluents and a subset of the fluents hidden in the states, with the actions disordered and parallelized | ## Extraction Techniques +Depending on the observation type, different extraction techniques can be used to extract the relevant information from the observations. These are currently the techniques implemented: + - [Observer](macq/extract.html#observer) - [SLAF](macq/extract.html#slaf) - [ARMS](macq/extract.html#arms) - [AMDN](macq/extract.html#amdn) - [LOCM](macq/extract.html#locm) - -# API Documentation diff --git a/macq/__init__.py b/macq/__init__.py index 56b4bc15..30bd90a9 100644 --- a/macq/__init__.py +++ b/macq/__init__.py @@ -1,4 +1,7 @@ """ .. include:: ../README.md + +---- + .. include:: ../docs/index.md """ diff --git a/macq/generate/__init__.py b/macq/generate/__init__.py index 238a38b3..784d9579 100644 --- a/macq/generate/__init__.py +++ b/macq/generate/__init__.py @@ -1,4 +1,5 @@ from . import pddl from .plan import Plan +import csv -__all__ = ["pddl", "Plan"] +__all__ = ["pddl", "Plan", "csv"] diff --git a/macq/generate/csv.py b/macq/generate/csv.py index 3cd7aba2..1d27915d 100644 --- a/macq/generate/csv.py +++ b/macq/generate/csv.py @@ -10,7 +10,13 @@ def load(fname: str, act_col: str, plan_id_col: str = None): - """Loads a trace file as a csv into a `TraceList`. + """Loads a trace file as a CSV into a `TraceList`. + + The CSV file should have the following properties: + + - An action column that contains the action names. + - Fluent columns with cells containing 0 or 1. + - (optionally) A plan ID column that contains the plan ID to separate the traces. Args: fname (str): diff --git a/pyproject.toml b/pyproject.toml index 9787c3bd..1f4be169 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,65 @@ [build-system] requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" + +[project] +name = "macq" +version = "0.3.11" +description = "Action model acquisition from state trace data." +# author="Ethan Callanan, Rebecca De Venezia, Victoria Armstrong, Alison Parades, Tathagata Chakraborti, Christian Muise", +authors = [ + {name = "Ethan Callanan"}, + {name = "Rebecca De Venezia"}, + {name = "Victoria Armstrong"}, + {name = "Alison Parades"}, + {name = "Tathagata Chakraborti"}, + {name = "Christian Muise", email = "christian.muise@queensu.ca"}, +] +maintainers = [ + {name = "Christian Muise", email = "christian.muise@queensu.ca"} +] +readme = "README.md" +license = {file = "LICENSE"} +keywords = ["planning", "action model acquisition"] +requires-python = ">=3.8" +classifiers = [ + "Intended Audience :: Science/Research", + "Topic :: Scientific/Engineering", + "Topic :: Scientific/Engineering :: Mathematics", + "Programming Language :: Python", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3 :: Only", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", +] +dependencies = [ + "tarski", + "requests", + "rich", + "nnf", + "python-sat", + "bauhaus", + "numpy", + "clingo", + "graphviz", + "networkx", + "pydot", +] + +[project.optional-dependencies] +dev = [ + "pytest", + "pytest-cov", + "flake8", + "black", + "pre-commit", +] + +[project.urls] +Homepage = "https://macq.planning.domains" +Documentation = "https://ai-planning.github.io/macq/" +Repository = "https://github.com/ai-planning/macq" diff --git a/setup.py b/setup.py index 92d5cbaf..844898f5 100644 --- a/setup.py +++ b/setup.py @@ -1,67 +1,5 @@ -from setuptools import setup, find_packages -VERSION = "0.3.10" +from setuptools import setup -NAME = "macq" -DESCRIPTION = "Action model acquisition from state trace data." - -DEPENDENCIES = [ - "tarski", - "requests", - "rich", - "nnf", - "python-sat", - "bauhaus", - "numpy", - "clingo", - "graphviz", - "networkx", - "pydot", -] - -DEV_DEPENDENCIES = [ - "pytest", - "pytest-cov", - "flake8", - "black", - "pre-commit", -] - -CLASSIFIERS = [ - "Intended Audience :: Science/Research", - "Topic :: Scientific/Engineering", - "Topic :: Scientific/Engineering :: Mathematics", - "Programming Language :: Python", - "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", - "Programming Language :: Python :: 3 :: Only", - "License :: OSI Approved :: MIT License", - "Operating System :: OS Independent", -] - -with open("LICENSE", "r", encoding="utf-8") as f: - LICENSE = f.read() - -with open("README.md", "r", encoding="utf-8") as f: - LONG_DESCRIPTION = f.read() - -setup( - name=NAME, - version=VERSION, - author="Ethan Callanan, Rebecca De Venezia, Victoria Armstrong, Alison Parades, Tathagata Chakraborti, Christian Muise", - author_email="christian.muise@queensu.ca", - license="MIT", - description=DESCRIPTION, - long_description=LONG_DESCRIPTION, - long_description_content_type="text/markdown", - keywords="planning model acquisition trace", - url="https://github.com/ai-planning/macq", - classifiers=CLASSIFIERS, - python_requires=">=3.9", - install_requires=DEPENDENCIES, - extras_require={"dev": DEV_DEPENDENCIES}, -) +setup()