Skip to content

Commit d2e6f9e

Browse files
pi8027pi8027
authored
Merge pull request #89 from math-comp/doc
Documentation
2 parents 97a2ceb + 892c683 commit d2e6f9e

File tree

3 files changed

+294
-42
lines changed

3 files changed

+294
-42
lines changed

‎README.md

Lines changed: 142 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,16 @@ Follow the instructions on https://github.com/coq-community/templates to regener
1313

1414

1515
This library provides `ring`, `field`, `lra`, `nra`, and `psatz` tactics for
16-
algebraic structures of the Mathematical Components library. The `ring` tactic
17-
works with any `comRingType` (commutative ring) or `comSemiRingType`
18-
(commutative semiring). The `field` tactic works with any `fieldType` (field).
19-
The other (Micromega) tactics work with any `realDomainType` (totally ordered
20-
integral domain) or `realFieldType` (totally ordered field). Algebra Tactics
21-
do not provide a way to declare instances, like the `Add Ring` and `Add Field`
22-
commands, but use canonical structure inference instead. Therefore, each of
23-
these tactics works with any canonical (or abstract) instance of the
24-
respective structure declared through Hierarchy Builder. Another key feature
25-
of Algebra Tactics is that they automatically push down ring morphisms and
26-
additive functions to leaves of ring/field expressions before applying the
27-
proof procedures.
16+
the Mathematical Components library. These tactics use the algebraic
17+
structures defined in the MathComp library and their canonical instances for
18+
the instance resolution, and do not require any special instance declaration,
19+
like the `add Ring` and `Add Field` commands. Therefore, each of these tactics
20+
works with any instance of the respective structure, including concrete
21+
instances declared through Hierarchy Builder, abstract instances, and mixed
22+
concrete and abstract instances, e.g., `int * R` where `R` is an abstract
23+
commutative ring. Another key feature of Algebra Tactics is that they
24+
automatically push down ring morphisms and additive functions to leaves of
25+
ring/field expressions before applying the proof procedures.
2826

2927
## Meta
3028

@@ -62,10 +60,139 @@ make install
6260
```
6361

6462

65-
## Caveat
6663

67-
The `lra`, `nra`, and `psatz` tactics are considered experimental features and
68-
subject to change.
64+
## Documentation
65+
66+
**Caveat: the `lra`, `nra`, and `psatz` tactics are considered experimental
67+
features and subject to change.**
68+
69+
This Coq library provides an adaptation of the
70+
[`ring`, `field`](https://coq.inria.fr/refman/addendum/ring),
71+
[`lra`, `nra`, and `psatz`](https://coq.inria.fr/refman/addendum/micromega)
72+
tactics to the MathComp library.
73+
See the Coq reference manual for the basic functionalities of these tactics.
74+
The descriptions of these tactics below mainly focus on the differences
75+
between ones provided by Coq and ones provided by this library, including the
76+
additional features introduced by this library.
77+
78+
### The `ring` tactic
79+
80+
The `ring` tactic solves a goal of the form `p = q :> R` representing a
81+
polynomial equation. The type `R` must have a canonical `comRingType`
82+
(commutative ring) or at least `comSemiRingType` (commutative semiring)
83+
instance.
84+
The `ring` tactic solves the equation by normalizing each side as a
85+
polynomial, whose coefficients are either integers `Z` (if `R` is a
86+
`comRingType`) or natural numbers `N`.
87+
88+
The `ring` tactic can decide the given polynomial equation modulo given
89+
monomial equations. The syntax to use this feature is `ring: t_1 .. t_n` where
90+
each `t_i` is a proof of equality `m_i = p_i`, `m_i` is a monomial, and `p_i`
91+
is a polynomial.
92+
Although the `ring` tactic supports ring homomorphisms (explained below), all
93+
the monomials and polynomials `m_1, .., m_n, p_1, .., p_n, p, q` must have the
94+
same type `R` for the moment.
95+
96+
Each tactic provided by this library has a preprocessor and supports
97+
applications of (semi)ring homomorphisms and additive functions (N-module or
98+
Z-module homomorphisms).
99+
For example, suppose `f : S -> T` and `g : R -> S` are ring homomorphisms. The
100+
preprocessor turns a ring sub-expression of the form `f (x + g (y * z))` into
101+
`f x + f (g y) * f (g z)`.
102+
A composition of homomorphisms from the initial objects `nat`, `N`, `int`, and
103+
`Z` is automatically normalized to the canonical one. For example, if `R` in
104+
the above example is `int`, the result of the preprocessing should be
105+
`f x + y%:~R * z%:~R` where `f \o g : int -> T` is replaced with `intr`
106+
(`_%:~R`).
107+
Thanks to the preprocessor, the `ring` tactic supports the following
108+
constructs apart from homomorphism applications:
109+
- `GRing.zero` (`0%R`),
110+
- `GRing.add` (`+%R`),
111+
- `addn`,
112+
- `N.add`,
113+
- `Z.add`,
114+
- `GRing.natmul`,
115+
- `GRing.opp` (`-%R`),
116+
- `Z.opp`,
117+
- `Z.sub`,
118+
- `intmul`,
119+
- `GRing.one` (`1%R`),
120+
- `GRing.mul` (`*%R`),
121+
- `muln`,
122+
- `N.mul`,
123+
- `Z.mul`,
124+
- `GRing.exp`,[^constant_exponent]
125+
- `exprz`,[^constant_exponent]
126+
- `expn`,[^constant_exponent]
127+
- `N.pow`,[^constant_exponent]
128+
- `Z.pow`,[^constant_exponent]
129+
- `S`,
130+
- `Posz`,
131+
- `Negz`, and
132+
- constants of type `nat`, `N`, or `Z`.
133+
134+
[^constant_exponent]: The exponent must be a constant value. In addition, it
135+
must be non-negative for `exprz`.
136+
137+
### The `field` tactic
138+
139+
The `field` tactic solves a goal of the form `p = q :> F` representing a
140+
rational equation. The type `F` must have a canonical `fieldType` (field)
141+
instance.
142+
The `field` tactic solves the equation by normalizing each side to a pair of
143+
two polynomials representing a fraction, whose coefficients are integers `Z`.
144+
As is the case for the `ring` tactic, the `field` tactic can decide the given
145+
rational equation modulo given monomial equations. The syntax to use this
146+
feature is the same as the `ring` tactic: `field: t_1 .. t_n`.
147+
148+
The `field` tactic generates proof obligations that all the denominators in
149+
the equation are not zero.
150+
A proof obligation of the form `p * q != 0 :> F` is always automatically
151+
reduced to `p != 0 /\ q != 0`.
152+
If the field `F` is a `numFieldType` (partially ordered field), a proof
153+
obligation of the form `c%:~R != 0 :> F` where `c` is a non-zero integer
154+
constant is automatically resolved.
155+
156+
The `field` tactic has a preprocessor similar to the `ring` tactic.
157+
In addition ot the constructs supported by the `ring` tactic, the `field`
158+
tactic supports `GRing.inv` and `exprz` with a negative exponent.
159+
160+
### The `lra`, `nra`, and `psatz` tactics
161+
162+
The `lra` tactic is a decision procedure for linear real arithmetic. The `nra`
163+
and `psatz` tactics are incomplete proof procedures for non-linear real
164+
arithmetic.
165+
The carrier type must have a canonical `realDomainType` (totally ordered
166+
integral domain) or `realFieldType` (totally ordered field) instance.
167+
The multiplicative inverse is supported only if the carrier type is a
168+
`realFieldType`.
169+
170+
If the carrier type is not a `realFieldType` but a `realDomainType`, these
171+
three tactics use the same preprocessor as the `ring` tactic.
172+
If the carrier type is a `realFieldType`, these tactics support `GRing.inv`
173+
and `exprz` with a negative exponent.
174+
In contrast to the `field` tactic, these tactics push down the multiplicative
175+
inverse through multiplication and exponentiation, e.g., turning `(x * y)^-1`
176+
into `x^-1 * y^-1`.
177+
178+
## Files
179+
180+
- `theories/`
181+
- `common.v`: provides the reflexive preprocessors (syntax, interpretation
182+
function, and normalization functions),
183+
- `common.elpi`: provides the reification procedure for (semi)ring and
184+
module expressions, except for the case that the carrier type is a
185+
`realFieldType` in the `lra`, `nra`, and `psatz` tactics,
186+
- `ring.v`: provides the Coq code specific to the `ring` and `field`
187+
tactics, including the reflection lemmas,
188+
- `ring.elpi`: provides the Elpi code specific to the `ring` and `field`
189+
tactics,
190+
- `ring_tac.elpi`: provides the entry point for the `ring` tactic,
191+
- `field_tac.elpi`: provides the entry point for the `field` tactic,
192+
- `lra.v`: provides the Coq code specific to the `lra`, `nra`, and `psatz`
193+
tactics, including the reflection lemmas,
194+
- `lra.elpi`: provides the Elpi code specific to the `lra`, `nra`, and
195+
`psatz` tactics, including the reification procedure and the entry point.
69196

70197
## Credits
71198

‎coq-mathcomp-algebra-tactics.opam

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,16 @@ license: "CECILL-B"
1313
synopsis: "Ring, field, lra, nra, and psatz tactics for Mathematical Components"
1414
description: """
1515
This library provides `ring`, `field`, `lra`, `nra`, and `psatz` tactics for
16-
algebraic structures of the Mathematical Components library. The `ring` tactic
17-
works with any `comRingType` (commutative ring) or `comSemiRingType`
18-
(commutative semiring). The `field` tactic works with any `fieldType` (field).
19-
The other (Micromega) tactics work with any `realDomainType` (totally ordered
20-
integral domain) or `realFieldType` (totally ordered field). Algebra Tactics
21-
do not provide a way to declare instances, like the `Add Ring` and `Add Field`
22-
commands, but use canonical structure inference instead. Therefore, each of
23-
these tactics works with any canonical (or abstract) instance of the
24-
respective structure declared through Hierarchy Builder. Another key feature
25-
of Algebra Tactics is that they automatically push down ring morphisms and
26-
additive functions to leaves of ring/field expressions before applying the
27-
proof procedures."""
16+
the Mathematical Components library. These tactics use the algebraic
17+
structures defined in the MathComp library and their canonical instances for
18+
the instance resolution, and do not require any special instance declaration,
19+
like the `add Ring` and `Add Field` commands. Therefore, each of these tactics
20+
works with any instance of the respective structure, including concrete
21+
instances declared through Hierarchy Builder, abstract instances, and mixed
22+
concrete and abstract instances, e.g., `int * R` where `R` is an abstract
23+
commutative ring. Another key feature of Algebra Tactics is that they
24+
automatically push down ring morphisms and additive functions to leaves of
25+
ring/field expressions before applying the proof procedures."""
2826

2927
build: [make "-j%{jobs}%"]
3028
install: [make "install"]

‎meta.yml

Lines changed: 142 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,16 @@ synopsis: >-
1010
1111
description: |-
1212
This library provides `ring`, `field`, `lra`, `nra`, and `psatz` tactics for
13-
algebraic structures of the Mathematical Components library. The `ring` tactic
14-
works with any `comRingType` (commutative ring) or `comSemiRingType`
15-
(commutative semiring). The `field` tactic works with any `fieldType` (field).
16-
The other (Micromega) tactics work with any `realDomainType` (totally ordered
17-
integral domain) or `realFieldType` (totally ordered field). Algebra Tactics
18-
do not provide a way to declare instances, like the `Add Ring` and `Add Field`
19-
commands, but use canonical structure inference instead. Therefore, each of
20-
these tactics works with any canonical (or abstract) instance of the
21-
respective structure declared through Hierarchy Builder. Another key feature
22-
of Algebra Tactics is that they automatically push down ring morphisms and
23-
additive functions to leaves of ring/field expressions before applying the
24-
proof procedures.
13+
the Mathematical Components library. These tactics use the algebraic
14+
structures defined in the MathComp library and their canonical instances for
15+
the instance resolution, and do not require any special instance declaration,
16+
like the `add Ring` and `Add Field` commands. Therefore, each of these tactics
17+
works with any instance of the respective structure, including concrete
18+
instances declared through Hierarchy Builder, abstract instances, and mixed
19+
concrete and abstract instances, e.g., `int * R` where `R` is an abstract
20+
commutative ring. Another key feature of Algebra Tactics is that they
21+
automatically push down ring morphisms and additive functions to leaves of
22+
ring/field expressions before applying the proof procedures.
2523
2624
publications:
2725
- pub_url: https://drops.dagstuhl.de/opus/volltexte/2022/16738/
@@ -87,10 +85,139 @@ dependencies:
8785
namespace: mathcomp.algebra_tactics
8886

8987
documentation: |-
90-
## Caveat
9188
92-
The `lra`, `nra`, and `psatz` tactics are considered experimental features and
93-
subject to change.
89+
## Documentation
90+
91+
**Caveat: the `lra`, `nra`, and `psatz` tactics are considered experimental
92+
features and subject to change.**
93+
94+
This Coq library provides an adaptation of the
95+
[`ring`, `field`](https://coq.inria.fr/refman/addendum/ring),
96+
[`lra`, `nra`, and `psatz`](https://coq.inria.fr/refman/addendum/micromega)
97+
tactics to the MathComp library.
98+
See the Coq reference manual for the basic functionalities of these tactics.
99+
The descriptions of these tactics below mainly focus on the differences
100+
between ones provided by Coq and ones provided by this library, including the
101+
additional features introduced by this library.
102+
103+
### The `ring` tactic
104+
105+
The `ring` tactic solves a goal of the form `p = q :> R` representing a
106+
polynomial equation. The type `R` must have a canonical `comRingType`
107+
(commutative ring) or at least `comSemiRingType` (commutative semiring)
108+
instance.
109+
The `ring` tactic solves the equation by normalizing each side as a
110+
polynomial, whose coefficients are either integers `Z` (if `R` is a
111+
`comRingType`) or natural numbers `N`.
112+
113+
The `ring` tactic can decide the given polynomial equation modulo given
114+
monomial equations. The syntax to use this feature is `ring: t_1 .. t_n` where
115+
each `t_i` is a proof of equality `m_i = p_i`, `m_i` is a monomial, and `p_i`
116+
is a polynomial.
117+
Although the `ring` tactic supports ring homomorphisms (explained below), all
118+
the monomials and polynomials `m_1, .., m_n, p_1, .., p_n, p, q` must have the
119+
same type `R` for the moment.
120+
121+
Each tactic provided by this library has a preprocessor and supports
122+
applications of (semi)ring homomorphisms and additive functions (N-module or
123+
Z-module homomorphisms).
124+
For example, suppose `f : S -> T` and `g : R -> S` are ring homomorphisms. The
125+
preprocessor turns a ring sub-expression of the form `f (x + g (y * z))` into
126+
`f x + f (g y) * f (g z)`.
127+
A composition of homomorphisms from the initial objects `nat`, `N`, `int`, and
128+
`Z` is automatically normalized to the canonical one. For example, if `R` in
129+
the above example is `int`, the result of the preprocessing should be
130+
`f x + y%:~R * z%:~R` where `f \o g : int -> T` is replaced with `intr`
131+
(`_%:~R`).
132+
Thanks to the preprocessor, the `ring` tactic supports the following
133+
constructs apart from homomorphism applications:
134+
- `GRing.zero` (`0%R`),
135+
- `GRing.add` (`+%R`),
136+
- `addn`,
137+
- `N.add`,
138+
- `Z.add`,
139+
- `GRing.natmul`,
140+
- `GRing.opp` (`-%R`),
141+
- `Z.opp`,
142+
- `Z.sub`,
143+
- `intmul`,
144+
- `GRing.one` (`1%R`),
145+
- `GRing.mul` (`*%R`),
146+
- `muln`,
147+
- `N.mul`,
148+
- `Z.mul`,
149+
- `GRing.exp`,[^constant_exponent]
150+
- `exprz`,[^constant_exponent]
151+
- `expn`,[^constant_exponent]
152+
- `N.pow`,[^constant_exponent]
153+
- `Z.pow`,[^constant_exponent]
154+
- `S`,
155+
- `Posz`,
156+
- `Negz`, and
157+
- constants of type `nat`, `N`, or `Z`.
158+
159+
[^constant_exponent]: The exponent must be a constant value. In addition, it
160+
must be non-negative for `exprz`.
161+
162+
### The `field` tactic
163+
164+
The `field` tactic solves a goal of the form `p = q :> F` representing a
165+
rational equation. The type `F` must have a canonical `fieldType` (field)
166+
instance.
167+
The `field` tactic solves the equation by normalizing each side to a pair of
168+
two polynomials representing a fraction, whose coefficients are integers `Z`.
169+
As is the case for the `ring` tactic, the `field` tactic can decide the given
170+
rational equation modulo given monomial equations. The syntax to use this
171+
feature is the same as the `ring` tactic: `field: t_1 .. t_n`.
172+
173+
The `field` tactic generates proof obligations that all the denominators in
174+
the equation are not zero.
175+
A proof obligation of the form `p * q != 0 :> F` is always automatically
176+
reduced to `p != 0 /\ q != 0`.
177+
If the field `F` is a `numFieldType` (partially ordered field), a proof
178+
obligation of the form `c%:~R != 0 :> F` where `c` is a non-zero integer
179+
constant is automatically resolved.
180+
181+
The `field` tactic has a preprocessor similar to the `ring` tactic.
182+
In addition ot the constructs supported by the `ring` tactic, the `field`
183+
tactic supports `GRing.inv` and `exprz` with a negative exponent.
184+
185+
### The `lra`, `nra`, and `psatz` tactics
186+
187+
The `lra` tactic is a decision procedure for linear real arithmetic. The `nra`
188+
and `psatz` tactics are incomplete proof procedures for non-linear real
189+
arithmetic.
190+
The carrier type must have a canonical `realDomainType` (totally ordered
191+
integral domain) or `realFieldType` (totally ordered field) instance.
192+
The multiplicative inverse is supported only if the carrier type is a
193+
`realFieldType`.
194+
195+
If the carrier type is not a `realFieldType` but a `realDomainType`, these
196+
three tactics use the same preprocessor as the `ring` tactic.
197+
If the carrier type is a `realFieldType`, these tactics support `GRing.inv`
198+
and `exprz` with a negative exponent.
199+
In contrast to the `field` tactic, these tactics push down the multiplicative
200+
inverse through multiplication and exponentiation, e.g., turning `(x * y)^-1`
201+
into `x^-1 * y^-1`.
202+
203+
## Files
204+
205+
- `theories/`
206+
- `common.v`: provides the reflexive preprocessors (syntax, interpretation
207+
function, and normalization functions),
208+
- `common.elpi`: provides the reification procedure for (semi)ring and
209+
module expressions, except for the case that the carrier type is a
210+
`realFieldType` in the `lra`, `nra`, and `psatz` tactics,
211+
- `ring.v`: provides the Coq code specific to the `ring` and `field`
212+
tactics, including the reflection lemmas,
213+
- `ring.elpi`: provides the Elpi code specific to the `ring` and `field`
214+
tactics,
215+
- `ring_tac.elpi`: provides the entry point for the `ring` tactic,
216+
- `field_tac.elpi`: provides the entry point for the `field` tactic,
217+
- `lra.v`: provides the Coq code specific to the `lra`, `nra`, and `psatz`
218+
tactics, including the reflection lemmas,
219+
- `lra.elpi`: provides the Elpi code specific to the `lra`, `nra`, and
220+
`psatz` tactics, including the reification procedure and the entry point.
94221
95222
## Credits
96223

0 commit comments

Comments
 (0)