thousandproblems 0.1.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. thousandproblems-0.3.0/CHANGELOG.md +32 -0
  2. {thousandproblems-0.1.0/src/thousandproblems.egg-info → thousandproblems-0.3.0}/PKG-INFO +180 -6
  3. thousandproblems-0.3.0/README.md +319 -0
  4. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/pyproject.toml +6 -2
  5. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems/__init__.py +15 -3
  6. thousandproblems-0.3.0/src/thousandproblems/__main__.py +7 -0
  7. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems/_cparser.c +371 -24
  8. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems/_pyparser.py +98 -12
  9. thousandproblems-0.3.0/src/thousandproblems/cli.py +856 -0
  10. thousandproblems-0.3.0/src/thousandproblems/discover.py +239 -0
  11. thousandproblems-0.3.0/src/thousandproblems/download.py +148 -0
  12. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems/library.py +37 -2
  13. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems/nodes.py +45 -1
  14. thousandproblems-0.3.0/src/thousandproblems/search.py +549 -0
  15. thousandproblems-0.3.0/src/thousandproblems/stats.py +392 -0
  16. thousandproblems-0.3.0/src/thousandproblems/updates.py +231 -0
  17. thousandproblems-0.3.0/src/thousandproblems/validate.py +208 -0
  18. {thousandproblems-0.1.0 → thousandproblems-0.3.0/src/thousandproblems.egg-info}/PKG-INFO +180 -6
  19. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems.egg-info/SOURCES.txt +13 -1
  20. thousandproblems-0.3.0/src/thousandproblems.egg-info/entry_points.txt +2 -0
  21. thousandproblems-0.3.0/tests/test_cli.py +703 -0
  22. thousandproblems-0.3.0/tests/test_discover.py +253 -0
  23. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/tests/test_tptp.py +198 -0
  24. thousandproblems-0.3.0/tests/test_updates.py +209 -0
  25. thousandproblems-0.1.0/CHANGELOG.md +0 -8
  26. thousandproblems-0.1.0/README.md +0 -146
  27. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/LICENSE +0 -0
  28. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/MANIFEST.in +0 -0
  29. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/benchmarks/bench.py +0 -0
  30. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/setup.cfg +0 -0
  31. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/setup.py +0 -0
  32. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems/_cparser.pyi +0 -0
  33. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems/py.typed +0 -0
  34. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems.egg-info/dependency_links.txt +0 -0
  35. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/src/thousandproblems.egg-info/top_level.txt +0 -0
  36. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/tests/corpus.py +0 -0
  37. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/tests/test_backends.py +0 -0
  38. {thousandproblems-0.1.0 → thousandproblems-0.3.0}/tests/test_library.py +0 -0
@@ -0,0 +1,32 @@
1
+ # Changelog
2
+
3
+ ## Unreleased
4
+
5
+ - Python 3.15: binary wheels with the C parser, and 3.15 in the test matrix.
6
+ - A `thousandproblems` command (also `python -m thousandproblems`) with the subcommands
7
+ `fetch` (problems with their axioms), `download` (the whole library), `validate` (check a
8
+ local install), `find`, `stats` and `search`.
9
+ - `thousandproblems.search`: an offline version of TPTP2T's problem-property search over a
10
+ local library, using a cached index of the problem headers.
11
+ - `thousandproblems.stats`: `syntax_stats` and `SPC` read a problem's `% Syntax` and `% SPC`
12
+ header lines; `compute_stats` works out dialect, roles, atoms, predicates, functions,
13
+ variables and depths from the formulae.
14
+ - `thousandproblems.validate.validate_library` and `thousandproblems.download.download_library`.
15
+ - `Library.problem_files(name)`: a problem and every file it includes.
16
+ - `thousandproblems discover`: find TPTP libraries on this machine, check them, and print the
17
+ command that sets `$TPTP`, or add it to the shell's startup file (`--set`; `setx` on Windows).
18
+ - `thousandproblems refresh` (and `thousandproblems.updates.check_for_updates`): look up the
19
+ latest TPTP release, clear cached website downloads from older releases, and compare a local
20
+ library with it. Other commands remind you after 30 days without a check (y / n / snooze);
21
+ `THOUSANDPROBLEMS_NO_UPDATE_CHECK=1` turns that off.
22
+
23
+ ## 0.1.0
24
+
25
+ - `Variable.index` and `TypedVariable.index`: the distinct variables of a formula are numbered
26
+ 1, 2, 3 ... in order of first appearance (scoped by quantifier; 0 outside a formula).
27
+ - `TPTPFile.symbols` and `AnnotatedFormula.symbols`: the symbol table, a tuple of
28
+ `Symbol(name, arity)` in order of first appearance, without `$` and `$$` symbols.
29
+ - First release: parser and printer for every TPTP language (`thf`, `tff`, `tcf`, `fof`,
30
+ `cnf`, `tpi`), with a C extension and a pure-Python fallback that build identical trees.
31
+ - `fetch_problem` / `open_library`: read problems, and expand their includes, from a TPTP
32
+ folder, a tarball or the TPTP website.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: thousandproblems
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: Fast parser and printer for the TPTP problem and solution syntax (thf, tff, tcf, fof, cnf, tpi).
5
5
  Author-email: Ontology Portal <pypi@ontologyportal.org>
6
6
  License: GNU GENERAL PUBLIC LICENSE
@@ -691,6 +691,7 @@ Classifier: Programming Language :: Python :: 3.11
691
691
  Classifier: Programming Language :: Python :: 3.12
692
692
  Classifier: Programming Language :: Python :: 3.13
693
693
  Classifier: Programming Language :: Python :: 3.14
694
+ Classifier: Programming Language :: Python :: 3.15
694
695
  Classifier: Programming Language :: Python :: Implementation :: CPython
695
696
  Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
696
697
  Classifier: Topic :: Software Development :: Compilers
@@ -731,11 +732,47 @@ Import it as `thousandproblems`; the examples below alias it to `tptp`.
731
732
  >>> ax.language, ax.name, ax.role
732
733
  ('fof', 'ax1', 'axiom')
733
734
  >>> ax.formula.quantifier, ax.formula.variables
734
- ('!', (Variable(name='X'),))
735
+ ('!', (Variable(name='X', index=1),))
735
736
  >>> print(ax)
736
737
  fof(ax1,axiom,! [X] : (p(X) => q(X))).
737
738
  ```
738
739
 
740
+ ## Variable indexes and the symbol table
741
+
742
+ Each `Variable` has an `index`: the distinct variables of one formula are numbered 1, 2, 3 ... in
743
+ order of first appearance.
744
+
745
+ ```python
746
+ >>> clause = tptp.parse("cnf(c, axiom, f(X) | f(Y) | g(X, f(Y))).").formulae[0]
747
+ >>> [(v.name, v.index) for v in tptp.walk(clause.formula) if isinstance(v, tptp.Variable)]
748
+ [('X', 1), ('Y', 2), ('X', 1), ('Y', 2)]
749
+ ```
750
+
751
+ A quantifier counts as the first appearance of the variables it binds, and every binding is its
752
+ own variable, so `! [Y,X] : p(X,Y)` numbers Y 1 and X 2, and `(! [X] : p(X)) & (! [X] : q(X))`
753
+ gives its two `X` the indexes 1 and 2. Numbering restarts for each formula, and a variable that
754
+ is not part of a formula (in an annotation, or built by hand) has index 0. `index` is not
755
+ compared, so `Variable("X") == Variable("X", 1)`.
756
+
757
+ `problem.symbols` is the symbol table: a tuple of `Symbol(name, arity)`, one for each distinct
758
+ function, constant or predicate the formulae use, in order of first appearance. `f/1` and `f/2`
759
+ are different symbols, and a constant has arity 0.
760
+
761
+ ```python
762
+ >>> problem = tptp.parse("cnf(a, axiom, p(f(a), X) | ~ q(f(a,b))). cnf(b, axiom, p(c, Y)).")
763
+ >>> [str(s) for s in problem.symbols]
764
+ ['p/2', 'f/1', 'a/0', 'q/1', 'f/2', 'b/0', 'c/0']
765
+ >>> problem.formulae[1].symbols
766
+ (Symbol(name='p', arity=2), Symbol(name='c', arity=0))
767
+ ```
768
+
769
+ Variables, equality, numbers, distinct objects, `$` and `$$` symbols (`$true`, `$less` ...),
770
+ type declarations and annotations are not symbols. In THF, `f @ a` uses the symbols `f/0` and
771
+ `a/0`. Each formula has its own `symbols`, and the file's table is rebuilt when
772
+ `expand_includes` brings other files in, so it only covers formulae that are really there.
773
+
774
+ ## Functions
775
+
739
776
  | Function | |
740
777
  | --- | --- |
741
778
  | `parse(text, filename=None)` | Parse the text of a file. |
@@ -794,6 +831,143 @@ tarball. For anything more than a handful of problems, download the library.
794
831
  Reading a compressed tarball means decompressing up to each file, so unpack it
795
832
  (and use the folder) if you will read many problems.
796
833
 
834
+ ## Command line
835
+
836
+ Installing the package adds a `thousandproblems` command (`python -m thousandproblems` works
837
+ too). Commands that need a library take `-L/--library` with a folder, a tarball or a server
838
+ URL. Without it they use the folder named by `$TPTP`, and `fetch` and `stats` fall back to the
839
+ TPTP website.
840
+
841
+ ```sh
842
+ # the whole library (about 1 GB): the latest release, or --version 9.0.0; --list shows them all
843
+ thousandproblems download -o ~/tptp # prints e.g. ~/tptp/TPTP-v10.0.0
844
+ export TPTP=~/tptp/TPTP-v10.0.0
845
+
846
+ # a few problems, with the axiom files they include, saved in the standard layout
847
+ thousandproblems fetch SET001-1 'SEU14*' -o problems/
848
+ thousandproblems fetch SET001-1 --expand # print it, includes replaced by their formulae
849
+
850
+ # already have a library somewhere? find it, and set $TPTP for new terminals
851
+ thousandproblems discover ~/datasets --set
852
+
853
+ # is this a usable TPTP library? (exit status 1 if not)
854
+ thousandproblems validate ~/tptp/TPTP-v10.0.0 --includes
855
+
856
+ # where is it?
857
+ thousandproblems find SET001-1 'SYO00?^1' SET001-0.ax
858
+
859
+ # dialect, status, symbols, variables ...
860
+ thousandproblems stats SET001-1
861
+ thousandproblems stats my_problem.p --symbols --json
862
+ ```
863
+
864
+ `validate` checks the standard layout: the `Problems/` and `Axioms/` folders, three-letter
865
+ domain folders, and problem files named after their domain. `--includes` checks that every
866
+ include can be found, and `--parse` also parses every file (slow). A missing `Documents/`,
867
+ `Generators/`, `Scripts/` or `TPTP2X/` folder is only a warning, since a trimmed copy still
868
+ works; `--strict` makes warnings fail too.
869
+
870
+ `discover` looks for libraries: folders holding `Problems/` and `Axioms/`, searched four levels
871
+ deep (`--depth`) under the folders you name, or by default under the current folder, your home
872
+ folder, `/opt`, `/usr/local/share`, `/usr/share`, `/srv` and `/data`. It checks each one,
873
+ lists them (usable ones first, then newest), and prints the command that sets `$TPTP` for your
874
+ shell (`--shell bash|zsh|fish|sh|powershell|cmd` to choose another). With `--set`, or when you
875
+ say yes at the prompt, it adds that command to your shell's startup file (`~/.zshrc`,
876
+ `~/.bashrc`, or `~/.bash_profile` on macOS, a `conf.d` file for fish, `~/.profile` otherwise)
877
+ between marker comments, so running it again replaces that line rather than adding another.
878
+ On Windows it runs `setx` instead. Without a terminal, `--set` also needs `--yes`. A program
879
+ can't change the environment of the shell that started it, so the current terminal still needs
880
+ the printed command, or a new window.
881
+
882
+ `stats` shows the figures it works out from the formulae (with the included axioms, unless you
883
+ pass `--no-expand`) next to the `% Syntax` statistics that the TPTP header declares:
884
+
885
+ ```
886
+ Problem : SET001-1 (Problems/SET/SET001-1.p)
887
+ Domain : SET Set Theory
888
+ Title : Set members are superset members
889
+ Status : Unsatisfiable
890
+ Rating : 0.11 (v10.0.0)
891
+ SPC : CNF_UNS_RFO_NEQ_NHN (clause normal form, Unsatisfiable, real first-order, no equality, non-Horn)
892
+ Dialect : cnf [CNF]
893
+ Formulae : 9 (6 axiom, 2 hypothesis, 1 negated_conjecture)
894
+ Unit formulae : 3
895
+ Atoms : 17 (0 equality)
896
+ Symbols : 7 (arity 0-2)
897
+ predicates : 3 (arity 2-2)
898
+ functions : 1 (arity 2-2)
899
+ constants : 3 (arity 0-0)
900
+ Variables : 13 (bound: 13 !) (0 singleton)
901
+
902
+ Declared in the header (% Syntax), covering the problem with its includes:
903
+ clauses : 9 (3 unt; 1 nHn; 8 RR)
904
+ literals : 17 (0 equ; 8 neg)
905
+ ...
906
+ ```
907
+
908
+ ### Keeping up with new TPTP releases
909
+
910
+ The website only serves the current release, so problems cached from it go out of date when a
911
+ new release comes out. `thousandproblems refresh` looks up the latest release on tptp.org,
912
+ deletes cached downloads that come from an older one (they are fetched again when next
913
+ needed), and compares your local library (`-L` or `$TPTP`) with the latest release.
914
+ `--index` also rebuilds the search index.
915
+
916
+ ```
917
+ $ thousandproblems refresh
918
+ latest TPTP release : v10.0.0
919
+ online cache : held v9.3.0; cleared 12 files, so problems are fetched again from v10.0.0
920
+ local library : /data/TPTP-v9.3.0 is v9.3.0; get v10.0.0 with 'thousandproblems download'
921
+ ```
922
+
923
+ If you haven't checked for 30 days, the next command asks first:
924
+
925
+ ```
926
+ You have not checked for a new TPTP library version in 30 days, check now? [y]es / [n]o / [s]nooze for thirty days:
927
+ ```
928
+
929
+ `n` asks again the next day and `s` waits another 30 days. Without a terminal (in scripts and
930
+ pipelines) you get a one-line warning on stderr instead, at most once a day. Set
931
+ `THOUSANDPROBLEMS_NO_UPDATE_CHECK=1` to turn the reminder off, e.g. in CI. The time of the last
932
+ check is kept in `state.json` in the cache directory, and the version the online cache holds
933
+ in a `VERSION` file next to the cached files.
934
+
935
+ ### Searching by problem properties (TPTP2T)
936
+
937
+ `search` covers the problem-properties part of the [TPTP2T](https://tptp.org/cgi-bin/TPTP2T)
938
+ form, run offline against a local library: domain, logical form, first-order subform, problem
939
+ version, status, rating, numbers of formulae, unit formulae, atoms, types, datatypes,
940
+ codatatypes, symbols, predicates, functions, the arities, equality, unit equality, variables
941
+ and binders, and arithmetic.
942
+
943
+ ```sh
944
+ thousandproblems search --form FOF --status THM --rating 0.5..1 --equality none
945
+ thousandproblems search --domain SET,SEU --form THF --format table
946
+ thousandproblems search --form not:CNF --predicates '>1' --function-arity 0 --count
947
+ thousandproblems search --form TF0 --arithmetic yes | thousandproblems fetch - -o out/
948
+ ```
949
+
950
+ Lists are comma-separated and match any item. Numbers take `N`, `MIN..MAX`, `MIN..`, `..MAX`,
951
+ `>N`, `>=N`, `<N` or `<=N`, and `not:` negates a criterion like TPTP2T's `~` box. All
952
+ criteria must hold. `thousandproblems search --help` lists them all. The answers come from the
953
+ problem headers (`% SPC`, `% Status`, `% Rating`, `% Version` and `% Syntax`), which are
954
+ indexed on first use (a couple of seconds for a folder; a tarball has to be decompressed once)
955
+ and cached in `$THOUSANDPROBLEMS_CACHE` until the library changes. TPTP2T's *solution*
956
+ properties (which systems solved a problem, and how) come from the TSTP solution library, not
957
+ the problem library, so `search` does not offer them.
958
+
959
+ The same is available from Python:
960
+
961
+ ```python
962
+ from thousandproblems.search import search
963
+ for record in search("/data/TPTP-v10.0.0", form="FOF", status="THM", rating="unsolved"):
964
+ print(record.name, record.rating, record.stat("formulae"))
965
+ ```
966
+
967
+ `thousandproblems.stats` (`compute_stats`, `syntax_stats`, `SPC`),
968
+ `thousandproblems.validate.validate_library` and `thousandproblems.download.download_library`
969
+ are the other building blocks the commands use.
970
+
797
971
  ## Which parser is running?
798
972
 
799
973
  ```python
@@ -821,10 +995,10 @@ Measured on an Apple M-series laptop, Python 3.14, on generated problems of 0.4
821
995
 
822
996
  | | pure Python | C | speedup |
823
997
  | --- | --- | --- | --- |
824
- | cnf | 0.259 s | 0.024 s | 10.7x |
825
- | fof | 0.252 s | 0.024 s | 10.6x |
826
- | tff | 0.206 s | 0.018 s | 11.3x |
827
- | thf | 0.156 s | 0.012 s | 12.9x |
998
+ | cnf | 0.274 s | 0.026 s | 10.5x |
999
+ | fof | 0.269 s | 0.027 s | 10.0x |
1000
+ | tff | 0.221 s | 0.020 s | 10.9x |
1001
+ | thf | 0.160 s | 0.013 s | 12.4x |
828
1002
 
829
1003
  Run `python benchmarks/bench.py` to measure on your machine.
830
1004
 
@@ -0,0 +1,319 @@
1
+ # thousandproblems
2
+
3
+ A fast parser and printer for the [TPTP](https://tptp.org) ("Thousands of Problems for Theorem
4
+ Provers") problem and solution syntax.
5
+
6
+ - Every TPTP language: `thf`, `tff`, `tcf`, `fof`, `cnf` and `tpi`, including TF1/TH1
7
+ polymorphism, the TXF/non-classical extensions, `include` directives, and annotations
8
+ (sources, inference records, useful info).
9
+ - One AST for all of them, with exact line and column in every error.
10
+ - `str(node)` prints any node back as valid TPTP.
11
+ - **A C extension does the parsing**, roughly 10 times faster than the pure-Python parser. If
12
+ it isn't available the same parser runs in pure Python, with identical results.
13
+ - Fetches problems, with their axiom includes, from the TPTP website, a tarball or an
14
+ unpacked library.
15
+ - No dependencies. Python 3.11+.
16
+
17
+ ```
18
+ pip install thousandproblems
19
+ ```
20
+
21
+ Import it as `thousandproblems`; the examples below alias it to `tptp`.
22
+
23
+ ## Parsing
24
+
25
+ ```python
26
+ >>> import thousandproblems as tptp
27
+ >>> problem = tptp.parse("fof(ax1, axiom, ! [X] : (p(X) => q(X))).")
28
+ >>> ax = problem.formulae[0]
29
+ >>> ax.language, ax.name, ax.role
30
+ ('fof', 'ax1', 'axiom')
31
+ >>> ax.formula.quantifier, ax.formula.variables
32
+ ('!', (Variable(name='X', index=1),))
33
+ >>> print(ax)
34
+ fof(ax1,axiom,! [X] : (p(X) => q(X))).
35
+ ```
36
+
37
+ ## Variable indexes and the symbol table
38
+
39
+ Each `Variable` has an `index`: the distinct variables of one formula are numbered 1, 2, 3 ... in
40
+ order of first appearance.
41
+
42
+ ```python
43
+ >>> clause = tptp.parse("cnf(c, axiom, f(X) | f(Y) | g(X, f(Y))).").formulae[0]
44
+ >>> [(v.name, v.index) for v in tptp.walk(clause.formula) if isinstance(v, tptp.Variable)]
45
+ [('X', 1), ('Y', 2), ('X', 1), ('Y', 2)]
46
+ ```
47
+
48
+ A quantifier counts as the first appearance of the variables it binds, and every binding is its
49
+ own variable, so `! [Y,X] : p(X,Y)` numbers Y 1 and X 2, and `(! [X] : p(X)) & (! [X] : q(X))`
50
+ gives its two `X` the indexes 1 and 2. Numbering restarts for each formula, and a variable that
51
+ is not part of a formula (in an annotation, or built by hand) has index 0. `index` is not
52
+ compared, so `Variable("X") == Variable("X", 1)`.
53
+
54
+ `problem.symbols` is the symbol table: a tuple of `Symbol(name, arity)`, one for each distinct
55
+ function, constant or predicate the formulae use, in order of first appearance. `f/1` and `f/2`
56
+ are different symbols, and a constant has arity 0.
57
+
58
+ ```python
59
+ >>> problem = tptp.parse("cnf(a, axiom, p(f(a), X) | ~ q(f(a,b))). cnf(b, axiom, p(c, Y)).")
60
+ >>> [str(s) for s in problem.symbols]
61
+ ['p/2', 'f/1', 'a/0', 'q/1', 'f/2', 'b/0', 'c/0']
62
+ >>> problem.formulae[1].symbols
63
+ (Symbol(name='p', arity=2), Symbol(name='c', arity=0))
64
+ ```
65
+
66
+ Variables, equality, numbers, distinct objects, `$` and `$$` symbols (`$true`, `$less` ...),
67
+ type declarations and annotations are not symbols. In THF, `f @ a` uses the symbols `f/0` and
68
+ `a/0`. Each formula has its own `symbols`, and the file's table is rebuilt when
69
+ `expand_includes` brings other files in, so it only covers formulae that are really there.
70
+
71
+ ## Functions
72
+
73
+ | Function | |
74
+ | --- | --- |
75
+ | `parse(text, filename=None)` | Parse the text of a file. |
76
+ | `parse_file(path, *, expand_includes=False, tptp_root=None)` | Parse a file; optionally replace each `include` with the formulae it selects. |
77
+ | `parse_formula(text, language="fof")` | Parse one bare formula. |
78
+ | `walk(node)` | Iterate over a subtree, depth first. |
79
+ | `unquote(word)` | The raw text of a single-quoted word. |
80
+
81
+ Bad input raises `ParseError`, which has `.line`, `.column`, `.filename` and `.message`:
82
+
83
+ ```
84
+ x.p:3:9: expected ')', found '&'
85
+ p | q & r).
86
+ ^
87
+ ```
88
+
89
+ Nodes are frozen, hashable dataclasses (`Function`, `Variable`, `Or`, `ForAll`, `Implies` ...).
90
+ `|` and `&` chains are flat `NAry` nodes; parentheses are not represented. See the module
91
+ docstring (`help(thousandproblems)`) for the full description of the tree.
92
+
93
+ This is a *syntax* parser: it does not check sorts, arities, roles, or whether variables are
94
+ bound.
95
+
96
+ ## Fetching problems from a TPTP library
97
+
98
+ ```python
99
+ # the TPTP website (current release)
100
+ problem = tptp.fetch_problem("SET001-1", expand_includes=True)
101
+
102
+ # an unpacked library: the folder that holds Problems/ and Axioms/
103
+ problem = tptp.fetch_problem("SET001-1", "/data/TPTP-v9.0.0", expand_includes=True)
104
+
105
+ # a tarball (.tgz, .tar.gz, .tar.bz2, .tar.xz or plain .tar)
106
+ problem = tptp.fetch_problem("SET001-1", "/data/TPTP-v9.0.0.tgz", expand_includes=True)
107
+ ```
108
+
109
+ Without a source, the folder named by the `TPTP` environment variable is used if there is
110
+ one, and the website otherwise. To read several problems, open the library once:
111
+
112
+ ```python
113
+ with tptp.open_library("/data/TPTP-v9.0.0.tgz") as library:
114
+ for name in library.problem_names("SET")[:10]:
115
+ print(name, library.problem(name).header.status)
116
+ ```
117
+
118
+ Problem names follow the library's own scheme: `SET001-1`, `SEU140+3`, `SYN000_1`,
119
+ `SYO000^1`. `library.problem_text(name)` gives the raw source.
120
+
121
+ **The website allows only a few requests a minute.** The online library fetches a problem
122
+ together with the axiom files it includes in one request, and caches everything in
123
+ `$THOUSANDPROBLEMS_CACHE` (default: your platform's cache directory), so repeat reads cost nothing.
124
+ If the server says you are going too fast you get `RateLimited`, with the time to wait; nothing
125
+ is retried for you. Only the current release is available online; for another version, open its
126
+ tarball. For anything more than a handful of problems, download the library.
127
+
128
+ Reading a compressed tarball means decompressing up to each file, so unpack it
129
+ (and use the folder) if you will read many problems.
130
+
131
+ ## Command line
132
+
133
+ Installing the package adds a `thousandproblems` command (`python -m thousandproblems` works
134
+ too). Commands that need a library take `-L/--library` with a folder, a tarball or a server
135
+ URL. Without it they use the folder named by `$TPTP`, and `fetch` and `stats` fall back to the
136
+ TPTP website.
137
+
138
+ ```sh
139
+ # the whole library (about 1 GB): the latest release, or --version 9.0.0; --list shows them all
140
+ thousandproblems download -o ~/tptp # prints e.g. ~/tptp/TPTP-v10.0.0
141
+ export TPTP=~/tptp/TPTP-v10.0.0
142
+
143
+ # a few problems, with the axiom files they include, saved in the standard layout
144
+ thousandproblems fetch SET001-1 'SEU14*' -o problems/
145
+ thousandproblems fetch SET001-1 --expand # print it, includes replaced by their formulae
146
+
147
+ # already have a library somewhere? find it, and set $TPTP for new terminals
148
+ thousandproblems discover ~/datasets --set
149
+
150
+ # is this a usable TPTP library? (exit status 1 if not)
151
+ thousandproblems validate ~/tptp/TPTP-v10.0.0 --includes
152
+
153
+ # where is it?
154
+ thousandproblems find SET001-1 'SYO00?^1' SET001-0.ax
155
+
156
+ # dialect, status, symbols, variables ...
157
+ thousandproblems stats SET001-1
158
+ thousandproblems stats my_problem.p --symbols --json
159
+ ```
160
+
161
+ `validate` checks the standard layout: the `Problems/` and `Axioms/` folders, three-letter
162
+ domain folders, and problem files named after their domain. `--includes` checks that every
163
+ include can be found, and `--parse` also parses every file (slow). A missing `Documents/`,
164
+ `Generators/`, `Scripts/` or `TPTP2X/` folder is only a warning, since a trimmed copy still
165
+ works; `--strict` makes warnings fail too.
166
+
167
+ `discover` looks for libraries: folders holding `Problems/` and `Axioms/`, searched four levels
168
+ deep (`--depth`) under the folders you name, or by default under the current folder, your home
169
+ folder, `/opt`, `/usr/local/share`, `/usr/share`, `/srv` and `/data`. It checks each one,
170
+ lists them (usable ones first, then newest), and prints the command that sets `$TPTP` for your
171
+ shell (`--shell bash|zsh|fish|sh|powershell|cmd` to choose another). With `--set`, or when you
172
+ say yes at the prompt, it adds that command to your shell's startup file (`~/.zshrc`,
173
+ `~/.bashrc`, or `~/.bash_profile` on macOS, a `conf.d` file for fish, `~/.profile` otherwise)
174
+ between marker comments, so running it again replaces that line rather than adding another.
175
+ On Windows it runs `setx` instead. Without a terminal, `--set` also needs `--yes`. A program
176
+ can't change the environment of the shell that started it, so the current terminal still needs
177
+ the printed command, or a new window.
178
+
179
+ `stats` shows the figures it works out from the formulae (with the included axioms, unless you
180
+ pass `--no-expand`) next to the `% Syntax` statistics that the TPTP header declares:
181
+
182
+ ```
183
+ Problem : SET001-1 (Problems/SET/SET001-1.p)
184
+ Domain : SET Set Theory
185
+ Title : Set members are superset members
186
+ Status : Unsatisfiable
187
+ Rating : 0.11 (v10.0.0)
188
+ SPC : CNF_UNS_RFO_NEQ_NHN (clause normal form, Unsatisfiable, real first-order, no equality, non-Horn)
189
+ Dialect : cnf [CNF]
190
+ Formulae : 9 (6 axiom, 2 hypothesis, 1 negated_conjecture)
191
+ Unit formulae : 3
192
+ Atoms : 17 (0 equality)
193
+ Symbols : 7 (arity 0-2)
194
+ predicates : 3 (arity 2-2)
195
+ functions : 1 (arity 2-2)
196
+ constants : 3 (arity 0-0)
197
+ Variables : 13 (bound: 13 !) (0 singleton)
198
+
199
+ Declared in the header (% Syntax), covering the problem with its includes:
200
+ clauses : 9 (3 unt; 1 nHn; 8 RR)
201
+ literals : 17 (0 equ; 8 neg)
202
+ ...
203
+ ```
204
+
205
+ ### Keeping up with new TPTP releases
206
+
207
+ The website only serves the current release, so problems cached from it go out of date when a
208
+ new release comes out. `thousandproblems refresh` looks up the latest release on tptp.org,
209
+ deletes cached downloads that come from an older one (they are fetched again when next
210
+ needed), and compares your local library (`-L` or `$TPTP`) with the latest release.
211
+ `--index` also rebuilds the search index.
212
+
213
+ ```
214
+ $ thousandproblems refresh
215
+ latest TPTP release : v10.0.0
216
+ online cache : held v9.3.0; cleared 12 files, so problems are fetched again from v10.0.0
217
+ local library : /data/TPTP-v9.3.0 is v9.3.0; get v10.0.0 with 'thousandproblems download'
218
+ ```
219
+
220
+ If you haven't checked for 30 days, the next command asks first:
221
+
222
+ ```
223
+ You have not checked for a new TPTP library version in 30 days, check now? [y]es / [n]o / [s]nooze for thirty days:
224
+ ```
225
+
226
+ `n` asks again the next day and `s` waits another 30 days. Without a terminal (in scripts and
227
+ pipelines) you get a one-line warning on stderr instead, at most once a day. Set
228
+ `THOUSANDPROBLEMS_NO_UPDATE_CHECK=1` to turn the reminder off, e.g. in CI. The time of the last
229
+ check is kept in `state.json` in the cache directory, and the version the online cache holds
230
+ in a `VERSION` file next to the cached files.
231
+
232
+ ### Searching by problem properties (TPTP2T)
233
+
234
+ `search` covers the problem-properties part of the [TPTP2T](https://tptp.org/cgi-bin/TPTP2T)
235
+ form, run offline against a local library: domain, logical form, first-order subform, problem
236
+ version, status, rating, numbers of formulae, unit formulae, atoms, types, datatypes,
237
+ codatatypes, symbols, predicates, functions, the arities, equality, unit equality, variables
238
+ and binders, and arithmetic.
239
+
240
+ ```sh
241
+ thousandproblems search --form FOF --status THM --rating 0.5..1 --equality none
242
+ thousandproblems search --domain SET,SEU --form THF --format table
243
+ thousandproblems search --form not:CNF --predicates '>1' --function-arity 0 --count
244
+ thousandproblems search --form TF0 --arithmetic yes | thousandproblems fetch - -o out/
245
+ ```
246
+
247
+ Lists are comma-separated and match any item. Numbers take `N`, `MIN..MAX`, `MIN..`, `..MAX`,
248
+ `>N`, `>=N`, `<N` or `<=N`, and `not:` negates a criterion like TPTP2T's `~` box. All
249
+ criteria must hold. `thousandproblems search --help` lists them all. The answers come from the
250
+ problem headers (`% SPC`, `% Status`, `% Rating`, `% Version` and `% Syntax`), which are
251
+ indexed on first use (a couple of seconds for a folder; a tarball has to be decompressed once)
252
+ and cached in `$THOUSANDPROBLEMS_CACHE` until the library changes. TPTP2T's *solution*
253
+ properties (which systems solved a problem, and how) come from the TSTP solution library, not
254
+ the problem library, so `search` does not offer them.
255
+
256
+ The same is available from Python:
257
+
258
+ ```python
259
+ from thousandproblems.search import search
260
+ for record in search("/data/TPTP-v10.0.0", form="FOF", status="THM", rating="unsolved"):
261
+ print(record.name, record.rating, record.stat("formulae"))
262
+ ```
263
+
264
+ `thousandproblems.stats` (`compute_stats`, `syntax_stats`, `SPC`),
265
+ `thousandproblems.validate.validate_library` and `thousandproblems.download.download_library`
266
+ are the other building blocks the commands use.
267
+
268
+ ## Which parser is running?
269
+
270
+ ```python
271
+ >>> tptp.BACKEND
272
+ 'c'
273
+ ```
274
+
275
+ The C extension is used when it is installed, and `BACKEND` is `"c"`. Otherwise (no wheel for
276
+ your platform and no compiler when installing from source, or you asked for it) the pure-Python
277
+ parser runs and `BACKEND` is `"python"`. Set `THOUSANDPROBLEMS_PURE_PYTHON=1` before importing to
278
+ force pure Python.
279
+
280
+ The C parser hands very deeply nested input (more than about a thousand levels of nested terms
281
+ or a few hundred of bare parentheses) to the Python parser, so that it can never overflow the
282
+ C stack, even on a thread with a small one. You get the same result either way, just more
283
+ slowly.
284
+
285
+ One thing the parser cannot control: CPython frees a very deeply nested tree recursively, using
286
+ a few hundred bytes of stack per level. Freeing a tree around a thousand levels deep on a thread
287
+ with a tiny stack (256 KB) crashed Python 3.14 on musl Linux, with either parser. If you handle
288
+ inputs like that, don't do it on threads with stacks that small; the default thread stack size on
289
+ every mainstream platform is fine.
290
+
291
+ Measured on an Apple M-series laptop, Python 3.14, on generated problems of 0.4 to 0.7 MB:
292
+
293
+ | | pure Python | C | speedup |
294
+ | --- | --- | --- | --- |
295
+ | cnf | 0.274 s | 0.026 s | 10.5x |
296
+ | fof | 0.269 s | 0.027 s | 10.0x |
297
+ | tff | 0.221 s | 0.020 s | 10.9x |
298
+ | thf | 0.160 s | 0.013 s | 12.4x |
299
+
300
+ Run `python benchmarks/bench.py` to measure on your machine.
301
+
302
+ ## Development
303
+
304
+ ```
305
+ python -m venv .venv && . .venv/bin/activate
306
+ pip install -e . # builds the C extension if there's a compiler
307
+ python -m unittest discover -s tests
308
+ THOUSANDPROBLEMS_PURE_PYTHON=1 python -m unittest discover -s tests # the fallback
309
+ ```
310
+
311
+ `tests/test_backends.py` runs the C and Python parsers side by side on the whole test corpus,
312
+ on generated problems and on thousands of randomly damaged ones, and requires identical trees
313
+ and identical error messages, lines and columns. If you change the grammar, change
314
+ `_pyparser.py` and `_cparser.c` together; that test will tell you if they drift apart.
315
+ `THOUSANDPROBLEMS_FUZZ_ROUNDS=4000` runs it harder.
316
+
317
+ Build-time switches: `THOUSANDPROBLEMS_PURE_PYTHON=1` builds without the extension (a pure
318
+ `py3-none-any` wheel), and `THOUSANDPROBLEMS_REQUIRE_EXT=1` makes a failed C compile an error
319
+ instead of a warning.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "thousandproblems"
7
- version = "0.1.0"
7
+ version = "0.3.0"
8
8
  description = "Fast parser and printer for the TPTP problem and solution syntax (thf, tff, tcf, fof, cnf, tpi)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -22,11 +22,15 @@ classifiers = [
22
22
  "Programming Language :: Python :: 3.12",
23
23
  "Programming Language :: Python :: 3.13",
24
24
  "Programming Language :: Python :: 3.14",
25
+ "Programming Language :: Python :: 3.15",
25
26
  "Programming Language :: Python :: Implementation :: CPython",
26
27
  "Topic :: Scientific/Engineering :: Artificial Intelligence",
27
28
  "Topic :: Software Development :: Compilers",
28
29
  "Typing :: Typed",
29
30
  ]
31
+ [project.scripts]
32
+ thousandproblems = "thousandproblems.cli:main"
33
+
30
34
  [project.urls]
31
35
  Home = "https://ontologyportal.org"
32
36
  Source = "https://github.com/ontologyportal/thousandproblems"
@@ -41,7 +45,7 @@ include-package-data = false
41
45
  thousandproblems = ["py.typed", "*.pyi"]
42
46
 
43
47
  [tool.cibuildwheel]
44
- build = "cp311-* cp312-* cp313-* cp314-*"
48
+ build = "cp311-* cp312-* cp313-* cp314-* cp315-*"
45
49
  skip = "*-musllinux_i686 *-manylinux_i686"
46
50
  build-verbosity = 1
47
51
  # The checks that the C parser really is in the wheel are in the test suite
@@ -10,7 +10,7 @@ directives, and annotations (sources, inference records, useful info).
10
10
  >>> ax.language, ax.name, ax.role
11
11
  ('fof', 'ax1', 'axiom')
12
12
  >>> ax.formula.quantifier, ax.formula.variables
13
- ('!', (Variable(name='X'),))
13
+ ('!', (Variable(name='X', index=1),))
14
14
  >>> print(ax)
15
15
  fof(ax1,axiom,! [X] : (p(X) => q(X))).
16
16
 
@@ -27,6 +27,18 @@ The AST is the same for all languages:
27
27
  :class:`Binary`. ``>`` is right-associative.
28
28
  * Constants are :class:`Function` with no arguments. Defined and system symbols keep
29
29
  their prefix, as in ``Function('$true')``.
30
+ * ``Variable.index`` numbers the distinct variables of a formula 1, 2, 3 ... in order of
31
+ first appearance, so in ``f(X) | f(Y) | g(X, f(Y))`` every ``X`` has index 1 and every
32
+ ``Y`` index 2. A quantifier counts as the appearance of the variables it binds, and each
33
+ binding is its own variable: the two ``X`` of ``(! [X] : p(X)) & (! [X] : q(X))`` get
34
+ indexes 1 and 2. Numbering starts again for each formula; a variable outside a formula (in
35
+ an annotation, or built by hand) has index 0.
36
+ * ``TPTPFile.symbols`` is the symbol table: a tuple of :class:`Symbol` ``(name, arity)``,
37
+ one for each distinct function, constant or predicate the formulae use, in order of first
38
+ appearance, so ``f/1`` and ``f/2`` are different symbols. Variables, equality, numbers,
39
+ distinct objects, ``$`` and ``$$`` symbols, type declarations and annotations are not
40
+ symbols. Each ``AnnotatedFormula`` has its own ``symbols`` too, and the file's table follows
41
+ ``expand_includes``.
30
42
  * Quotes are removed from a word when the result is still a valid lower-case word,
31
43
  so ``'cat'`` and ``cat`` compare equal, as the specification requires. Any other
32
44
  quoted word keeps its quotes; use :func:`unquote` to get the raw text.
@@ -59,7 +71,7 @@ from typing import Optional, Union
59
71
 
60
72
  from . import _pyparser
61
73
  from .nodes import * # noqa: F403
62
- from .nodes import _error_at, __all__ as _node_names
74
+ from .nodes import _error_at, _symbol_table, __all__ as _node_names
63
75
 
64
76
  _LIBRARY_NAMES = ("DirectoryLibrary", "Library", "LibraryError", "OnlineLibrary", "ProblemNotFound",
65
77
  "RateLimited", "TarballLibrary", "fetch_problem", "open_library")
@@ -158,4 +170,4 @@ def _load(path: Path, root: Optional[Path], expand: bool, stack: tuple[Path, ...
158
170
  raise fail(f"{item.path!r} has no formulae named {sorted(missing)}")
159
171
  formulae = tuple(selected)
160
172
  inputs.extend(formulae)
161
- return TPTPFile(tuple(inputs), parsed.comments, parsed.filename)
173
+ return TPTPFile(tuple(inputs), parsed.comments, parsed.filename, _symbol_table(i for i in inputs if isinstance(i, AnnotatedFormula)))
@@ -0,0 +1,7 @@
1
+ """``python -m thousandproblems``: see :mod:`thousandproblems.cli`."""
2
+
3
+ import sys
4
+
5
+ from .cli import main
6
+
7
+ sys.exit(main())