API Reference

[JoanEspasa]

Hi everyone :)

I feel that tarksi is a diamond in the rough: At the moment, to explore the features that the library has one needs to browse the source code. I found that there are many useful functionalities that are not documented or shown in the notebooks.

I'm aware that documentation is costly in terms of time, and not trivial to produce. I was wondering if it would be much work to produce at least an API reference of some sorts (a-la javadocs) so users can get at least an helicopter view of what is implemented.

[miquelramirez]

Thanks for being a 💎👐 Joan and sticking with us :)

We do have some tutorials that perhaps need to be better advertised. Suggestions of specific use cases for tarski that would be nice to be documented are very valuable for us to get a better idea of what are the blind spots and in what ways peeps use tarski. I hope too that this discussion forum will start to get populated with questions about how to use tarski and become a community-driven effort at documentation.

I recall that @gfrances was looking at the integration with Sphinx, but I am not sure of what is the status for that.

Ultimately, to get tarski docs and tutorials to a "polished" state we would need to hire someone (and the difficulty isn't funding as much as finding the right skills) or find some kind soul willing to volunteer time & energy.

[miquelramirez]

And guess what, we do have already a readthedocs site:

https://tarski.readthedocs.io/en/latest/

So definitely @gfrances finished the integration and I completely forgot about it! D'oh!

[haz]

Even with the readthedocs site, there's stuff that's hard to find (I've taken a dive into the code several times to find stuff).

I've three undergrads using it to varying degrees over the summer. Perhaps I can ask them what the major blindspots were/are/will be?

[miquelramirez]

That would be great, Chris.

[JoanEspasa]

That would be great Chris!

Personally I would be keen on seeing at least a list of classes/methods and a very short/schematic description on each. The code already has some comments, so I guess it is not that far off. In 3 weeks or so, after finishing the pile of marking I have to do, I would also be keen to start contributing a wee bit into that :)

[haz]

I'll add to this, but comments so far (prompt was "how might the documentation be improved given the work you've done so far"):

• More example usage cases/clarity in the documentation, especially when describing the types of parameters that a function needs. For example, GroundForwardSearchModel (among a lot of functions) describes that they need "ground operators" but it took me a while to deduce that that meant I needed to use the ground_problem_schemas_into_plain_operators function from LPGrounding.
• More documentation in the simple module under evaluators
• Generally, documenting what functions take, do, and return and what classes would be used for in the online API

[haz]

The the general API breakdown that @JoanEspasa mentions would cover a fair bit of this.

[haz]

So another simple matter that's caused many-a-headache over recent days -- having programmatic (and not just through strings) access to aspects of the problem. There may be a way to do all this properly, but it's not obvious how.

Assuming we've successfully parsed a domain (and possibly a problem) PDDL, we'd like to...

...get access to predicates, including their types

Seems as though the only way to get to this level is through FStripsWriter and parsing string exports.

...get access to a unified interface for fluents

Seems as though they're sometimes Atoms or CompoundFormulas or just string representations

...access the fluents on action effects/preconditions

Would hope that it's in the same format (object data structure) as fluents elsewhere in the library.

...access the types of objects in a grounded action/predicate

We'd like to be able to just look up from the Python object representing a PDDL object, what its type might be. Regardless of where this object has come from (action parameter, predicate argument, etc).

...have functions to parse actions and predicates in general

I guess this is more of a nice-to-have than an expected API that's missing...

---

Thoughts @gfrances @miquelramirez ?

[gfrances]

Hi Chris! Commenting on these individually:

• Programmatic access: definitely the Possible typo in "super" hierarchy element #1 use case for which we started developing the library, you should never have to print anything then parse again that, otherwise what's the point of using this. (Of course I'm not saying that the library is perfect and gives you access to everything, there might be something missing that we have to add, but we're definitely willing to add that). What info is it exactly that you are trying to access? Will probably need to improve documentation / tests on this.
• Unified interface for fluents: Definitely interested on addressing this too. Could you guys provide a quick list of places where you've detected the inconsistencies? Atoms and CompoundFormulas are different things, though. An Atom is a standard first-order logical atomic formula (i.e. predicate symbol applied to tuple of terms of appropriate length). A CompoundFormula is what is sometimes also called an "open formula": the combination of formulas through logical connectives.
• Accessing fluents: How are you guys doing this at the moment? The programmatic inspection of effects and preconditions is of course possible now, but maybe just not in the format you'd expect? In particular, say for preconditions, the precondition of an action is a standard tarski.syntax.formula; and from here you should be able to get all of the info you need. But it might make sense to add some kind of helper method that transforms the formula into a set of Atom objects, or similar. If you can give a description of your use case, that'd help.
• Accessing types in a ground atom or action: Definitely possible. Reading this and seeing the PRs, I suspect maybe you are using the output of the ASP grounding module? (Which is indeed represented in strings). Could be that some extra step is required there to convert everything back into tarski objects?
• **parse actions and predicates **: You mean as e.g. parsing a PDDL-represented predicate or action alone?
  say: (:action move \n:parameters (?from ?to) ...)?
  This should be possible, but the way tarski is designed now, we'll likely need to have all the relevant language info before being able to parse that (e.g.: if an action has precondition on(a,b), we'll need the knowledge that on is a binary predicate, etc.
  If we have the language object with the strictly necessary information beforehand, though, it should certainly be possible to do this.

[miquelramirez]

Documentation can always be improved but there is this

Programmatic Interface

https://tarski.readthedocs.io/en/latest/notebooks/parsing-and-inspecting-pddl.html

Which shows how to process a planning instance described in PDDL and then shows how to access each of the main elements of action schemas, predicates, etc.

It is no accident that the above is provided as a Jupyter notebook... It is meant for peeps to create a copy and go nuts exploring the library.

If the tutorial above was not relevant... I am not sure what to say.

Accessing fluents from ground representations

There is another specific tutorial for this

https://tarski.readthedocs.io/en/latest/notebooks/grounding-reachability-analysis.html

Unified access to fluents

There is no such a thing as a fluent in first order logic. Which the formal model that tarski uses.

Preconditions for instance are first order formulas, grounded or otherwise. And formulas in FOL have a non trivial structure: you can have atoms or formulas that are composites of atoms, the standard logical symbols (and, or, not), and quantifiers.

If any string is being offered by some function of the library instead of a formula, that is a bug and should be reported.

What I am understanding is that there is a request/want for a Fikes & Nilsson STRIPS instance-like module with an interface similar to that of the FD front-end, that flattens goals, initial states, preconditions and effects into lists of atoms, etc.

All the pieces are already in the package tarski.syntax.fstrips but maybe is there somebody contesting that STRIPS is a subset of FSTRIPS?

I can't recall if we have a visitor for flattening conjunctive formulas, but definitely worth taking a look through the tests exercising formula transformations. The CNF transform was refactored recently to spit out flat theories (as a set of sets of literals).

In any case, code snippets with use cases or errors obtained would go a long way to illustrate these issues.

[miquelramirez]

A good example of how a classical planner optimized for the IPC (including the IPC 2018 domains which are tricky) and that uses tarski can be found here:

https://github.com/LAPKT-dev/LAPKT-public/tree/Devel/src/pddl_interface/tarski_parse_ground

this may help bridging some gaps in the communication/understanding. Let me walk you through it.

The code consists of a C++ component (which is the adapter of the C++ LAPKT STRIPSProblem class) and a Python component (the module tarski_util.py). This Python component basically does all the processing that is necessary to end up with a pure Fikes & Nilsson STRIPS instance. The function process_formula in tarski_util.py above shows an example to eliminate quantifiers in a correct way when conditional effects are involved. Note as well that the code requires to pass to the C++ backend the string literals for every symbol so the planner can generate proper IPC compliant output (and enabling debugging). This is far from desirable, we couldn't figure out a way out of this.

In any case, I think it is fair to say that tarski plus the above is a significant improvement over 1) using ff as a library for parsing and grounding, and 2) using the Fast Downward front-end. Anybody can compare the three approaches (all implemented in the Devel branch of LAPKT-dev) and make their own minds about what works and what does not work for them.

Now let me get a bit introspective and share some "designer's notes" which may eventually find their way into a documentation (or a paper, who knows).

The code above just shows one way to adapt tarski to work with a C++ system which is by now quite long in the tooth (some interfaces were written in 2011-12). I am working on stuff which doesn't look at all like PDDL, and I have only needed to do very few adjustments to the library interfaces. I think this attests to the generality and flexibility of the approach we have taken to tarski.

What is that "approach"? It should be clear by now that tarski isn't just a "library for processing PDDL files". It is not, and never was meant to be that.

Our design (which has evolved in some surprising ways over the years) follows from the following observation. A planning instance is made of the following elements. To wit:

1. a FOL theory (our FirstOrderLanguage class) with sorts/types, predicates, functions, and sub-theories defining symbols with fixed interpretation (e.g. equality predicates, relational arithmetic predicates, algebraic operators), that @gfrances sometimes tries to convince me that are just syntactic sugar,

2. a semantic structure to interpret formulas and terms (our Model and evaluator concepts), and

3. sets of formulas defined over the theory which are 'tagged' with labels such as 'this atom is a fluent', 'this formula is the precondition of action a(x, y, z)' and so on.

The latter (hierarchies of) sets of formulas are associated with planning languages as diverse as PDDL 3.0 (the PDDL that captures FSTRIPS entirely), Scott's RDDL and J. Rintanen's NDL. Hence we usually provide "domain" and "instance" classes as separate modules, trying to strike a delicate balance between what is truly independent of a back-end (planner or otherwise) and what is specific to sets of instances (such as the IPC benchmarks).

It also illustrates that there are design decisions which tarski cannot take on behalf of the person writing a planner. The "problem" classes in tarski are light on functionality because we have always expected that people would take them and do further massaging to get the data into their planner data structures.

Now I have a vague understanding of what you want to achieve Christian, which is not to build planners. Yet you seem to be asking for the very same things that somebody who wants to write a STRIPS planner based on forward heuristic search would ask from tarski... plus a SAX-like interface for parsing (where the parsing is driven by inputs coming in discrete form, at different points in time).

More specific discussion of use cases (maybe opening issues with the tag question rather than posting them on a forum) would help us understand what you are trying to achieve, and will enable us to transfer to you our knowledge of these codes in a more efficient and satisfying manner.

[haz]

I've 3 concurrent threads of development using tarski in very different ways (none of which is a planner), so it's easy to get spun around as to what the hell is going on :P. Some of these will really push (I think) what's feasible to the limit: distributions of possible preconditions, of entire action theories even, partial groundings, etc.

Those notebooks are helpful to get started, but don't (and probably shouldn't) provide full coverage of what's going on. Something like [this] helps, but fails (without the docstring support) to detail the makeup (e.g., what we might find on action.?).

Wrt. the grand vision -- it's laudable! Shy of publishing the vision (or in addition to?) I think that should be posted front-and-center on the repo. Risk of the grand vision is that it runs is having the complexity become a barrier to the simpler use-cases. This can be remedied with adapters for the common use cases (STRIPS assumption would give a different interface than a full ADL one, for example), but I'm not sure if that's part of the vision as well? Kind of a keras-is-to-tensorflow equivalent. A grounded (pun intended example) that's made up...

>> from tarski.keras.STRIPS import parse

>> problem = parse('dom.pddl', 'prob.pddl').ground()

>> print(problem.actions[0].pddl())
  (:action put-down
	     :parameters (A)
	     :precondition (holding A)
	     :effect
	     (and (not (holding A))
		   (clear A)
		   (handempty)
		   (ontable A)))

>> print(problem.actions[0].ADD)
  {(clear A), (handempty), (ontable A)}

>> state1 = problem.init.progress(problem.actions[0])

>> state2 = state1.progress(problem.actions[3])

>> state2 |= problem.goal
  True

Sure, some of this is already there, some of this is whacky overloading (do we really want |= to do entailment? :P), and some of this is a solid dozen lines or so (ala this) condensed to a single line (and, yep, I've assumed that actions from dom/prob will fit into memory).

More specific discussion of use cases (maybe opening issues with the tag question rather than posting them on a forum) would help us understand what you are trying to achieve.

I like this idea. Going to take it a step further and suggest we post the fabricated python code we hoped would work + the places we looked to figure it out. Should lead to either a feature request (if the functionality's missing) or a documentation request.

We've tackled the bulk of the current issues on our plate with the help of the notebooks and our compiled docs, but I'll be sure to lob any further ones that come up as they do.

Cheers!