doc: add org-mode documentation for user tools
* doc/org/.gitignore, doc/org/genltl.org, doc/org/ioltl.org, doc/org/ltl2tgba.org, doc/org/ltl2tgta.org, doc/org/ltlcross.org, doc/org/ltlfilt.org, doc/org/randltl.org, doc/org/tools.org: New files.
This commit is contained in:
Alexandre Duret-Lutz
parent
2f5d961d10
commit
345b8c5b14
9 changed files with 2299 additions and 0 deletions
327
doc/org/randltl.org
Normal file
327
doc/org/randltl.org
Normal file
|
|
@ -0,0 +1,327 @@
|
|||
#+TITLE: =randltl=
|
||||
#+EMAIL spot@lrde.epita.fr
|
||||
#+OPTIONS: H:2 num:nil toc:t
|
||||
#+LINK_UP: file:tools.html
|
||||
|
||||
This tool generates random formulas. By default, it will generate one
|
||||
random LTL formula using atomic propositions supplied on the
|
||||
command-line. It can be instructed to generate random Boolean or PSL
|
||||
formulas instead, but let us first focus on LTL generation.
|
||||
|
||||
For instance to obtain one random LTL formula over the propositions
|
||||
=a=, =b=, or =c=, use:
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl a b c
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: G(Gb W (Gb M c))
|
||||
|
||||
Note that the result does not always use all atomic propositions.
|
||||
|
||||
The syntax of the formula output can be changed using the
|
||||
[[file:ioltl.org][common output options]]:
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports results
|
||||
randltl --help | sed -n '/Output options:/,/^$/p' | sed '1d;$d'
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: -8, --utf8 output using UTF-8 characters
|
||||
: -l, --lbt output in LBT's syntax
|
||||
: -p, --full-parentheses output fully-parenthesized formulas
|
||||
: -s, --spin output in Spin's syntax
|
||||
: --spot output in Spot's syntax (default)
|
||||
: --wring output in Wring's syntax
|
||||
|
||||
When you select Spin's or Wring's syntax, operators =W= and =M= are
|
||||
automatically rewritten using =U= and =R= (written =V= for Spin).
|
||||
When you select LBT's syntax, you should name you atomic propositions
|
||||
like =p0=, =p1=, etc... (Atomic proposition named differently will be
|
||||
output by Spot in double-quotes, but this is not supported by LBT.)
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -l p1 p2 p3
|
||||
randltl -8 p1 p2 p3
|
||||
randltl -s p1 p2 p3
|
||||
randltl --wring p1 p2 p3
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: G W G p2 M G p2 p3
|
||||
: □(□p2 W (□p2 M p3))
|
||||
: []((p3 U (p3 && []p2)) V ([]p2 || (p3 U (p3 && []p2))))
|
||||
: (G(((p3=1) U ((p3=1) * (G(p2=1)))) R ((G(p2=1)) + ((p3=1) U ((p3=1) * (G(p2=1)))))))
|
||||
|
||||
As you might guess from the above result, for a given set of atomic
|
||||
propositions (and on the same computer) the generated formula will
|
||||
always be the same. This is because each time =randltl= starts, it
|
||||
initialize the seed of the random number generator to =0=. This seed
|
||||
can be changed using the =--seed= option. For instance the following
|
||||
three commands:
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl a b c
|
||||
randltl --seed=123 a b c
|
||||
randltl --seed=0 a b c
|
||||
#+END_SRC
|
||||
|
||||
Will give three formulas in which the first and last are identical:
|
||||
|
||||
#+RESULTS:
|
||||
: G(Gb W (Gb M c))
|
||||
: X((c <-> F(a M Xc)) -> a)
|
||||
: G(Gb W (Gb M c))
|
||||
|
||||
When generating random formulas, we usually want large quantity of
|
||||
them. Rather than running =randltl= several times with different
|
||||
seeds, we can use the =-n= option to specify a number of formulas to
|
||||
produce.
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -n 5 a b c
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: G(Gb W (Gb M c))
|
||||
: !(GFb -> Fa)
|
||||
: (((c xor Xc) R c) R Gc) & !c
|
||||
: X(1 U Xb) M Fb
|
||||
: !XFb U !(Xa W 0)
|
||||
|
||||
By default =randltl= will never output the same formula twice (this
|
||||
can be changed with the =--allow-dups= option), so it may generate
|
||||
more formulas internally than it eventually prints. To ensure
|
||||
termination, for each output formula the number of ignored (because
|
||||
duplicated) random formulas that are generated is limited to 100000.
|
||||
Therefore in some situations, most likely when generating small
|
||||
formulas, with few atomic proposition, you may see =randltl= stop
|
||||
before the requested number of formulas has been output with an error
|
||||
message.
|
||||
|
||||
If the integer passed to =-n= is negative, =randltl= will attempt to
|
||||
generate as many formulas as it can. This is most useful when
|
||||
=randltl= is piped to =ltlfilt= to select random formulas matching a
|
||||
certain criterion, as we shall see later.
|
||||
|
||||
Besides the list of atomic propositions (=a b c= in our example) and
|
||||
the seed, several other parameters control the generation of the
|
||||
random formulas.
|
||||
|
||||
Initially, the random generator selects a tree size for the formula.
|
||||
The default size is =15=, but it can be changed using the =--tree-size=
|
||||
option. For instance in the following, for each formula the tree size
|
||||
will be chosen randomly in the range =22..30=.
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -n 5 a b c --tree-size=22..30
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: ((Fc W 0) M 1) & ((a | XXc) M (b W Fb))
|
||||
: (!(c | (a R Xb)) <-> (Xc R (a & c))) -> !a
|
||||
: 0
|
||||
: X(Xc R GX(1 U Xb)) & GX(b M Xc)
|
||||
: (!b -> ((c xor Fa) W b)) W (!Fb U a)
|
||||
|
||||
The tree size is just the number of nodes in the syntax tree of the
|
||||
formula during its construction. However because Spot automatically
|
||||
applies some /trivial simplifications/ during the construction of its
|
||||
formulas (e.g., =F(F(a)= is reduced to =F(a)=, =a&0= to =0=, etc.),
|
||||
the actual size of the formula output may be smaller than the
|
||||
tree size specified.
|
||||
|
||||
It is pretty common to obtain the formulas =0= or =1= among the first
|
||||
formulas output, since many random formulas trivially simplify to
|
||||
these. However because duplicate formulas are suppressed by default,
|
||||
they shall only occur once.
|
||||
|
||||
Stronger simplifications may be requested using the =-r= option, that
|
||||
implements many rewritings that helps Spot translators algorithms (so
|
||||
beware that using =-r= reduces the randomness of the output).
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -n 5 a b c --tree-size=22..30 -r
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: GFc & ((a | XXc) M Fb)
|
||||
: !a | (!c & (!a U X!b)) | (a & c & Xc)
|
||||
: 0
|
||||
: XG(b M Xc)
|
||||
: (((!c & Fa) | (c & G!a)) W b) W (G!b U a)
|
||||
|
||||
The generator build the syntax tree recursively from its root, by
|
||||
considering all operators that could be used for a given tree size (for
|
||||
example a tree-size of 2 disables binary operators). A /priority/ is
|
||||
associated to each operator, and the probability of this operator
|
||||
being selected is this priority over the sum of the priorities of all
|
||||
considered operators. The default priorities for each operator can
|
||||
be seen with =--dump-priorities=:
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl a b c --dump-priorities
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
#+begin_example
|
||||
Use --ltl-priorities to set the following LTL priorities:
|
||||
ap 3
|
||||
false 1
|
||||
true 1
|
||||
not 1
|
||||
F 1
|
||||
G 1
|
||||
X 1
|
||||
equiv 1
|
||||
implies 1
|
||||
xor 1
|
||||
R 1
|
||||
U 1
|
||||
W 1
|
||||
M 1
|
||||
and 1
|
||||
or 1
|
||||
#+end_example
|
||||
|
||||
Where =ap= stands for /atomic propositions/ (=a=, =b=, =c=). In this
|
||||
example, when the generator builds a leaf of the syntax tree (i.e., a
|
||||
subformula of tree-size 1), it must ignore all operators, and chose
|
||||
between =ap=, =false=, or =true=, and the odds of choosing =ap= is
|
||||
3/(3+1+1).
|
||||
|
||||
As indicated at the top of the output, these priorities can be changed
|
||||
using the =--ltl-priorities= options. The most common scenario is to
|
||||
disable some of the operators by giving them a null priority. The
|
||||
following example disables 6 operators, and augments the priority of
|
||||
=U= to 3 to favor its occurrence.
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -n 5 a b c --ltl-priorities 'xor=0,implies=0,equiv=0,W=0,M=0,X=0,U=3'
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: F(Fb U (c & Gb))
|
||||
: !(Fb U Fa)
|
||||
: ((Gc U c) U c) U Fc
|
||||
: 0
|
||||
: 1
|
||||
|
||||
When using =-r= to simplify generated formulas, beware that these
|
||||
rewritings may use operators that you disabled during the initial
|
||||
random generation: you may obtain a formula that uses =W= even if =W=
|
||||
has a null priority. (You can use =ltlfilt= to rewrite these
|
||||
operators if that is a problem.)
|
||||
|
||||
If the =--weak-fairness= option is used, for each random formula
|
||||
generated, a weak-fairness formula of the form =GF(a) & GF(b) & GF(c)=
|
||||
is generated for a subset of the atomic propositions and "ANDed" to
|
||||
the random formula. The =--tree-size= option has no influence on the
|
||||
weak-fairness formula appended.
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -n 5 a b c --weak-fairness
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: G(Gb W (Gb M c)) & GFb
|
||||
: GFb & !(GFb -> Fa) & GFa
|
||||
: GFb & (((c xor Xc) R c) R Gc) & !c
|
||||
: GFb & GFa & (X(1 U Xb) M Fb)
|
||||
: GFb & (!XFb U !(Xa W 0)) & GFc
|
||||
|
||||
|
||||
Boolean formulas may be output with the =-B= option:
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -B -n 5 a b c
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: !a -> !b
|
||||
: !(!(a -> (b xor c)) -> !a)
|
||||
: !c | (!c xor (c xor (c xor !c)))
|
||||
: !b
|
||||
: a xor !(!b <-> (!a -> c))
|
||||
|
||||
In that case, priorities should be set with =--boolean-priorities=.
|
||||
|
||||
Finally, PSL formulas may be output using the =-P= option. However
|
||||
keep in mind that since LTL formulas are PSL formulas, generating
|
||||
random PSL formula may produce many LTL formulas that do not use any
|
||||
PSL operator (this is even more so the case when simplifications are
|
||||
enabled with =-r=).
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -P -n 5 a b c
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
: G(Gb M ((c & Xb) | (!a M 1)))
|
||||
: !(Fa xor X({{c | {a xor !b}}[*]}[]-> Fb))
|
||||
: c & Gc
|
||||
: 0
|
||||
: 1
|
||||
|
||||
As shown with the =--dump-priorities= output below, tweaking the
|
||||
priorities used to generated PSL formulas requires three different
|
||||
options:
|
||||
|
||||
#+BEGIN_SRC sh :results verbatim :exports both
|
||||
randltl -P a b c --dump-priorities
|
||||
#+END_SRC
|
||||
#+RESULTS:
|
||||
#+begin_example
|
||||
Use --ltl-priorities to set the following LTL priorities:
|
||||
ap 3
|
||||
false 1
|
||||
true 1
|
||||
not 1
|
||||
F 1
|
||||
G 1
|
||||
X 1
|
||||
Closure 1
|
||||
equiv 1
|
||||
implies 1
|
||||
xor 1
|
||||
R 1
|
||||
U 1
|
||||
W 1
|
||||
M 1
|
||||
and 1
|
||||
or 1
|
||||
EConcat 1
|
||||
UConcat 1
|
||||
Use --sere-priorities to set the following SERE priorities:
|
||||
eword 1
|
||||
boolform 1
|
||||
star 1
|
||||
star_b 1
|
||||
and 1
|
||||
andNLM 1
|
||||
or 1
|
||||
concat 1
|
||||
fusion 1
|
||||
Use --boolean-priorities to set the following Boolean formula priorities:
|
||||
ap 3
|
||||
false 1
|
||||
true 1
|
||||
not 1
|
||||
equiv 1
|
||||
implies 1
|
||||
xor 1
|
||||
and 1
|
||||
or 1
|
||||
#+end_example
|
||||
|
||||
The =--ltl-priorities= option we have seen previously now recognize
|
||||
some new PSL-specific operators: =Closure= is the ={sere}= operator,
|
||||
=EConcat= is the ={sere}<>->f= operator, and =UConcat= is the
|
||||
={sere}[]->f= operator. When these operator are selected, they
|
||||
require a SERE argument which is generated according to the priorities
|
||||
set by =--sere-priorities=: =eword= is the empty word, =boolform= is a
|
||||
Boolean formula (generated using the priorities set by
|
||||
=--boolean-priorities=), =star= is the unbounded Kleen star, while
|
||||
=star_b= is the bounded version, and =andNLM= is the
|
||||
non-length-matching variant of the =and= operator.
|
||||
|
||||
# Local variables:
|
||||
# eval: (setenv "PATH" (concat "../../src/bin" path-separator (getenv "PATH")))
|
||||
# eval: (org-babel-do-load-languages 'org-babel-load-languages '((sh . t) (dot . t)))
|
||||
# eval: (setq org-confirm-babel-evaluate nil)
|
||||
# End:
|
||||
|
||||
|
||||
# LocalWords: randltl num toc LTL PSL SRC Gb sed utf UTF lbt LBT's
|
||||
# LocalWords: Xc GFb Gc Xb Fb XFb Xa dups ltlfilt Fc XXc GX GFc XG
|
||||
# LocalWords: rewritings ltl ap GF ANDed GFa boolean EConcat eword
|
||||
# LocalWords: UConcat boolform andNLM concat Kleen eval setenv setq
|
||||
# LocalWords: getenv
|
||||
Loading…
Add table
Add a link
Reference in a new issue