From 5c228339f869ff3101204e5c624063eeb3dcd8d5 Mon Sep 17 00:00:00 2001
From: PierreJean Spaenlehauer
Date: Thu, 4 Oct 2018 11:12:43 +0200
Subject: [PATCH] write README in markdown

README  137 
README.md  167 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 167 insertions(+), 137 deletions()
delete mode 100644 README
create mode 100644 README.md
diff git a/README b/README
deleted file mode 100644
index e60967a..0000000
 a/README
+++ /dev/null
@@ 1,137 +0,0 @@
This software is distributed under LGPL2.1+ (i.e., LGPL version 2.1 or later).

Please report bugs to .

I  Installation


This software can be compiled using GNU make with g++.
Running the command
 make
in the directory containing the source files builds three executable files:
rrspace, class_grp_arith and tests.

In order to build only one of these programs, use the command
 make
where is rrspace, class_grp_arith or tests

Compiling this software requires the NTL library (https://www.shoup.net/ntl/).
In order to compile the program "tests", the library cppunit is also required
(https://freedesktop.org/wiki/Software/cppunit/).

After compiling, the three following commands should succeed without any error:
 ./tests
 ./rrspace < example_rrspace_input
 ./class_grp_arith < example_class_grp_div_input

II  Usage


Examples of inputs for rr_space and class_grp_arith are provided in the files
example_rrspace_input and example_class_grp_div_input. The formats for the
mathematical objects are detailed in the next section.

Disclaimer: The algorithms implemented in this software are probabilistic, and
they have a probability of failure. Also, they rely on some genericity
assumptions (such as generic coordinates). Finally, some problems may arise in
small characteristic, for instance if the characteristic divides the degree of
the curve.
In case of failure, the most probable situation is that just starting again the
software with the same input will work. In the unlikely situation that it still
fails, changing the system of coordinates by doing a random linear change of
projective coordinates and by computing the curve equation and the divisors in
this new coordinate system may work. Finally, if none of this works, this means
that we are in the very unlikely case where all the possible denominators which
could be returned by the interpolation function vanish at singular points of
the curve (this case cannot occur if the curve is smooth). In this case, please
use another model of the curve.

1) rrspace: the program rrspace computes the RiemannRoch space associated to a
given divisor D on a curve q. It reads its input on the standard input, and it
returns a basis of the RiemannRoch space on the standard output.

The format for its input (see next section for more details) is





where represents a divisor whose support does not contain any
singular point of the curve.

It outputs the following data:
  the dimension D of the RiemannRoch space;
  a denominator h, which is a bivariate polynomial;
  a list of D bivariate polynomials g_1, ..., g_D

The set of rational functions {g_1/h, ..., g_D/h} is a basis of the
RiemannRoch space.

2) class_grp_arith: this program takes as input two elements of the divisor
class group of a curve C of genus g and it returns a representation of the sum. Here, we
are given a curve, together with a degree 1 divisor on C. A class of divisors
(modulo principal divisors) is represented by an effective divisor D1 of degree
g: it represents the class of divisors equivalent to the degree0 divisor D1 
g*O.

class_grp_arith reads its input on the standard input, and it returns an
effective divisor of degree at most g on the standard output.

The format for its input (see next section for more details) is








The divisor provided on the 4th line must have degree 1. The two effective
divisors D1 and D2 provided on the last two lines must have degree .
The supports of all the divisors must not contain any singular point of the
curve.

The program returns a representation of a degreeg effective divisor D3 such that
(D1g*O) + (D2g*O) = (D3g*O)
in the divisor class group of C.

3) tests: this software does not take any input. It just runs two tests: one
for the computation of RiemannRoch spaces, and one for the arithmetic in the
divisor class group of a smooth quartic curve. It should output the string
"OK".

III  Data structures


This section details the data structures for the input of the programs
described in Section II.

: a prime number p

: a bivariate polynomial q = sum_{i=0}^d q_i(x)*y^i, where for all i,
q_i is a polynomial of degree at most di. The program requires that q_d(x) = 1.
The polynomial q is encoded as follows
 [ [ ... ] ]
where is the degree of the curve and is the list of coefficients
of the polynomial q_i. For instance if q_i(x) = sum_{j=0}^{r} q_{i,j} x^j,
then should be
 [ q_{i,0} q_{i,1} ... q_{i,r} ]

: the genus of the curve C described by the polynomial q. We decline all
responsability on the behavior of the programs if g is not the genus of the
curve.

: an effective divisor on C represented by two univariate
polynomials
 < >
Each polynomial is described by the list of its coefficients
 [ f_0 f_1 ... f_l ]
These two polynomials (referred to as f(X), g(X)) should satisfy the following
equality: q(X, g(X)) mod f(X) = 0.
They represent the effective divisor which is the sum of points (\alpha, \beta)
with multiplicity \gamma where \alpha is a root of multiplicity \gamma of f(X)
and \beta = g(\alpha).

: a divisor D on the curve C represented by two effective divisors D_+
and D_ such that D = D_+  D_.
 { }
diff git a/README.md b/README.md
new file mode 100644
index 0000000..4327cbd
 /dev/null
+++ b/README.md
@@ 0,0 +1,167 @@
+rrspace
+=======
+
+This software is distributed under LGPL2.1+ (i.e., LGPL version 2.1 or later).
+
+Please report bugs to .
+
+I  Installation
+
+
+This software can be compiled using GNU make with g++.
+
+Running the command
+
+```
+make
+```
+
+in the directory containing the source files builds three executable files:
+`rrspace`, `class_grp_arith` and `tests`.
+
+In order to build only one of these programs, use the command
+
+```
+make
+```
+
+where `` is `rrspace`, `class_grp_arith` or `tests`.
+
+Compiling this software requires the [NTL library](https://www.shoup.net/ntl/).
+In order to compile the program "tests", the
+[cppunit library](https://freedesktop.org/wiki/Software/cppunit/) is also required.
+
+After compiling, the three following commands should succeed without any error:
+
+```
+./tests
+./rrspace < example_rrspace_input
+./class_grp_arith < example_class_grp_div_input
+```
+
+II  Usage
+
+
+Examples of inputs for `rr_space` and `class_grp_arith` are provided in the files
+`example_rrspace_input` and `example_class_grp_div_input`. The formats for the
+mathematical objects are detailed in the next section.
+
+Disclaimer: The algorithms implemented in this software are probabilistic, and
+they have a probability of failure. Also, they rely on some genericity
+assumptions (such as generic coordinates). Finally, some problems may arise in
+small characteristic, for instance if the characteristic divides the degree of
+the curve. In case of failure, the most probable situation is that just
+starting again the software with the same input will work. In the unlikely
+situation that it still fails, changing the system of coordinates by doing a
+random linear change of projective coordinates and by computing the curve
+equation and the divisors in this new coordinate system may work. Finally, if
+none of this works, this means that we are in the very unlikely case where all
+the possible denominators which could be returned by the interpolation function
+vanish at singular points of the curve (this case cannot occur if the curve is
+smooth). In this case, please use another model of the curve.
+
+1. `rrspace`: the program `rrspace` computes the RiemannRoch space associated
+ to a given divisor D on a curve q. It reads its input on the standard input,
+ and it returns a basis of the RiemannRoch space on the standard output.
+
+ The format for its input (see next section for more details) is
+
+ ```
+
+
+
+ ```
+
+ where `` represents a divisor whose support does not contain any
+ singular point of the curve.
+
+ It outputs the following data:
+ * the dimension D of the RiemannRoch space;
+ * a denominator h, which is a bivariate polynomial;
+ * a list of D bivariate polynomials `f_1, ..., f_D`.
+
+ The set of rational functions `{f_1/h, ..., f_D/h}` is a basis of the
+ RiemannRoch space.
+
+2. `class_grp_arith`: this program takes as input two elements of the divisor
+ class group of a curve `C` of genus `g` and it returns a representation of the sum. Here, we
+ are given a curve, together with a degree 1 divisor on `C`. A class of divisors
+ (modulo principal divisors) is represented by an effective divisor `D1` of degree
+ `g`: it represents the class of divisors equivalent to the degree0 divisor `D1 
+ g*O`.
+
+ `class_grp_arith` reads its input on the standard input, and it returns an
+ effective divisor of degree at most `g` on the standard output.
+
+ The format for its input (see next section for more details) is
+
+ ```
+
+
+
+
+
+
+ ```
+
+ The divisor provided on the 4th line must have degree 1. The two effective
+ divisors `D1` and `D2` provided on the last two lines must have degree ``.
+ The supports of all the divisors must not contain any singular point of the
+ curve.
+
+ The program returns a representation of a degreeg effective divisor `D3` such that
+ `(D1g*O) + (D2g*O) = (D3g*O)` in the divisor class group of `C`.
+
+3. `tests`: this software does not take any input. It just runs two tests: one
+ for the computation of RiemannRoch spaces, and one for the arithmetic in the
+ divisor class group of a smooth quartic curve. It should output the string
+ `OK`.
+
+III  Data structures
+
+
+This section details the data structures for the input of the programs
+described in Section II.
+
+* ``: a prime number `p`
+
+* ``: a bivariate polynomial `q = sum_{i=0}^d q_i(x)*y^i`, where for all `i`,
+ `q_i` is a polynomial of degree at most `di`. The program requires that `q_d(x) = 1`.
+ The polynomial `q` is encoded as follows
+
+ ```
+ [ [ ... ] ]
+ ```
+
+ where `` is the degree of the curve and `` is the list of coefficients
+ of the polynomial `q_i`. For instance if `q_i(x) = sum_{j=0}^{r} q_{i,j} x^j`,
+ then `` should be
+
+ ```
+ [ q_{i,0} q_{i,1} ... q_{i,r} ]
+ ```
+
+* ``: the genus of the curve `C` described by the polynomial `q`. We decline all
+ responsability on the behavior of the programs if `g` is not the genus of the
+ curve.
+
+* ``: an effective divisor on `C` represented by two univariate
+ polynomials
+
+ ```
+ < >
+ ```
+
+ Each polynomial is described by the list of its coefficients `[ f_0 f_1 ... f_l ]`
+ These two polynomials (referred to as `f(X)`, `g(X)`) should satisfy the following
+ equality: `q(X, g(X)) mod f(X) = 0`.
+ They represent the effective divisor which is the sum of points `(\alpha, \beta)`
+ with multiplicity `\gamma` where `\alpha` is a root of multiplicity `\gamma` of `f(X)`
+ and `\beta = g(\alpha)`.
+
+* ``: a divisor `D` on the curve `C` represented by two effective divisors `D_+`
+ and `D_` such that `D = D_+  D_`
+
+ ```
+ { }
+ ```

2.22.0