mmarco/SIROCCO2
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Improved documentation for install in a Sage environment

Browse Source
This commit is contained in:
Miguel Marco 2017-02-28 15:45:42 +01:00
parent 13fbfb0f88
commit fa8f930c73
Signed by: mmarco
GPG Key ID: DD0114EDB7410592
1 changed files with 76 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
README.md
View File

@ -2,15 +2,15 @@
## General description. ## General description.
This is a library for computing homotopy continuation of a given root of one This is a library for computing homotopy continuation of a given root of one
dimensional sections of bivariate complex polynomials (of degree greater than 2). dimensional sections of bivariate complex polynomials (of degree greater than 2).
The output is a piecewise linear aproximation of the path followed by the root, The output is a piecewise linear aproximation of the path followed by the root,
with the property that there is a tubular neighborhood, with square transversal with the property that there is a tubular neighborhood, with square transversal
section, that contains the actual path, and there is a three times thicker tubular section, that contains the actual path, and there is a three times thicker tubular
neigborhood guaranted to contain no other root of the polynomial. This second neigborhood guaranted to contain no other root of the polynomial. This second
property ensures that the piecewise linear approximation computed from all roots property ensures that the piecewise linear approximation computed from all roots
of a polynomial form a topologically correct deformation of the actual braid, of a polynomial form a topologically correct deformation of the actual braid,
since the inner tubular neighborhoods cannot intersect. since the inner tubular neighborhoods cannot intersect.
The first version of the library was written in C, and provided only double The first version of the library was written in C, and provided only double
precission. This is the second version, rewritten in C++, and provides the precission. This is the second version, rewritten in C++, and provides the
@ -24,59 +24,59 @@ the [MPFR](http://www.mpfr.org/) and [GMP](https://gmplib.org/) libraries.
## Usage: ## Usage:
After installing the library, you can call it from any .cpp program by calling After installing the library, you can call it from any .cpp program by calling
the homotopyPath or homotopyPath_mp functions. In the file test/test_example you can see a simple the homotopyPath or homotopyPath_mp functions. In the file tests/sirocco_test.cpp
example you can see a simple example
### Double precission: ### Double precission:
The input of the homotopyPath function is the following: The input of the homotopyPath function is the following:
- An integer representing the total degree of the polynomial - An integer representing the total degree of the polynomial
- A malloc'ed array of double precission floats. Each four consecutive entries - A malloc'ed array of double precission floats. Each four consecutive entries
of this list represent a coefficient, in the form of a rectangular complex of this list represent a coefficient, in the form of a rectangular complex
interval. These four numbers represent the following: interval. These four numbers represent the following:
- the lower bound of the real part - the lower bound of the real part
- the upper bound of the real part - the upper bound of the real part
- the lower bound of the imaginary part - the lower bound of the imaginary part
- the upper bound of the imaginary part - the upper bound of the imaginary part
These coefficients are written in increasing deglex order. That is, the first These coefficients are written in increasing deglex order. That is, the first
coefficients are the corresponding to the monomials $1, x, y, x^2, x y, y^2, coefficients are the corresponding to the monomials $1, x, y, x^2, x y, y^2,
x^3, x^2 y, x y^2, y^3...$ x^3, x^2 y, x y^2, y^3...$
- A double precission float corresponding to the real part of an approximate - A double precission float corresponding to the real part of an approximate
solution y0 solution y0
- A double precission float corresponding to the imaginary part of an - A double precission float corresponding to the imaginary part of an
approximate solution y0 approximate solution y0
The use of complex intervals allows us to represent polynomials with non The use of complex intervals allows us to represent polynomials with non
rational coefficients (even transcendental): just give an interval that rational coefficients (even transcendental): just give an interval that
contains it. contains it.
y0 must be an approximation of a simple root of the univariate polynomial y0 must be an approximation of a simple root of the univariate polynomial
f(0,y). f(0,y).
For example, the input 1, [2.0, 2.0, 0.0, 0.0, 0.0, 0.0, 3.2, 3.2, -4.5, -4.5, For example, the input 1, [2.0, 2.0, 0.0, 0.0, 0.0, 0.0, 3.2, 3.2, -4.5, -4.5,
0.7, 0.7], 6.1, -3.3 would represent the polynomial of degree 1 f(x,y)=(2) + 0.7, 0.7], 6.1, -3.3 would represent the polynomial of degree 1 f(x,y)=(2) +
(3.2*i)*x + (-4.5 + 0.7)*y , and the approximate root y0= 6.1-3.3*i (3.2*i)*x + (-4.5 + 0.7)*y , and the approximate root y0= 6.1-3.3*i
The output is a malloc'ed array of double floats. The first entry represents The output is a malloc'ed array of double floats. The first entry represents
the number of points in the piecewise linear path. Then, each three entries the number of points in the piecewise linear path. Then, each three entries
correspond to one of these points. The first entry of these triplets is the x correspond to one of these points. The first entry of these triplets is the x
coordinate of the point (will be a real number between 0 and 1), the next two coordinate of the point (will be a real number between 0 and 1), the next two
are the real and imaginary parts of the y coordinate. are the real and imaginary parts of the y coordinate.
This path represents the movement of the root y0 of f(x,y) when x varies from 0 This path represents the movement of the root y0 of f(x,y) when x varies from 0
to 1. So for each t between 0 and 1, there is a value y_t which is the linear to 1. So for each t between 0 and 1, there is a value y_t which is the linear
interpolation of the returned values. The computation certifies that for each interpolation of the returned values. The computation certifies that for each
t, there is a square neighborhood centered around y_t that contains one and t, there is a square neighborhood centered around y_t that contains one and
only one root of f(t,y). That is, there is a tube around the piecewise linear only one root of f(t,y). That is, there is a tube around the piecewise linear
path that contains the actual path followed by y0. Moreover, the corresponding path that contains the actual path followed by y0. Moreover, the corresponding
tubes of two different roots computed this way will not intersect. tubes of two different roots computed this way will not intersect.
Note that the method might fail if there is a singularity (i.e. a value xt for Note that the method might fail if there is a singularity (i.e. a value xt for
which f(xt, y) has multiple roots). In that case, you will either get a NULL which f(xt, y) has multiple roots). In that case, you will either get a NULL
value, or an infinite running time. value, or an infinite running time.
### Arbitrary precission ### Arbitrary precission
@ -87,9 +87,9 @@ The input of the homotopyPath_mp function is the following:
- A malloc'ed array of mpfr_t numbers. As before, each four entries - A malloc'ed array of mpfr_t numbers. As before, each four entries
represent an (intervalar) coefficient of a polynomial, following represent an (intervalar) coefficient of a polynomial, following
increasing deglex order. increasing deglex order.
- A mpfr_t number corresponding to the real part of an approximate - A mpfr_t number corresponding to the real part of an approximate
solution y0 solution y0
- A mpfr_t number corresponding to the imaginary part of an - A mpfr_t number corresponding to the imaginary part of an
approximate solution y0 approximate solution y0
- An integer representing the precission to be used in the internal - An integer representing the precission to be used in the internal
computations (and the output). computations (and the output).
@ -100,12 +100,12 @@ equal to the length of the list of points.
### From [SageMath](https://www.sagemath.org) ### From [SageMath](https://www.sagemath.org)
If you have the library and headers installed correctly, you can call this If you have the library and headers installed correctly, you can call this
library from a [sagemath](https://www.sagemath.org) session. The relevant files library from a [sagemath](https://www.sagemath.org) session. The relevant files
for that are `sage-sirocco_interface.pyx` and `ZVK.py`. The first one contains for that are `sage-sirocco_interface.pyx` and `ZVK.py`. The first one contains
the interface code, and the second one several functions to compute the the interface code, and the second one several functions to compute the
fundamental group of the complement of a curve in the complex plane, using this fundamental group of the complement of a curve in the complex plane, using this
library. Reffer to the comments in `ZVK.py` for a more detailed explanation of library. Reffer to the comments in `ZVK.py` for a more detailed explanation of
the functions available there. the functions available there.
An example of session using this library can be the following An example of session using this library can be the following
@ -116,7 +116,7 @@ Compiling ./sage-sirocco_interface.pyx...
sage: load("ZVK.py") sage: load("ZVK.py")
sage: R.<x,y>=QQ[] sage: R.<x,y>=QQ[]
sage: f = x^4*y - x^2*y - y^2 + y sage: f = x^4*y - x^2*y - y^2 + y
sage: followstrand(f, 0, 2, 1) sage: followstrand(f, 0, 2, 1)
[(0.0, 1.0, 0.0), [(0.0, 1.0, 0.0),
(0.0625, 0.984619140625, 0.0), (0.0625, 0.984619140625, 0.0),
(0.12764635845490785, 0.9390733273680929, 0.0), (0.12764635845490785, 0.9390733273680929, 0.0),
@ -176,43 +176,56 @@ sage: followstrand(f, 0, 2, 1, 64)
(1.00000000000000000, 13.0000000000000000, 0.000000000000000000)] (1.00000000000000000, 13.0000000000000000, 0.000000000000000000)]
``` ```
The command followstrand shows the path followed y the root y0=1 of f(x,y) when The command followstrand shows the path followed y the root y0=1 of f(x,y) when
x varies from 0 o 2. It accepts an optional argument called `prec`, for the precission x varies from 0 o 2. It accepts an optional argument called `prec`, for the precission
to use. By default it is set to 53 (and uses the double precission implementation). If to use. By default it is set to 53 (and uses the double precission implementation). If
the computation fails, it falls back to a bigger precission until it succeeds). the computation fails, it falls back to a bigger precission until it succeeds).
The command fundamental_group uses this approach to The command fundamental_group uses this approach to
compute the braid monodromy associated to this polynomial, and then uses it to compute the braid monodromy associated to this polynomial, and then uses it to
get a presentation of the fundamental group of its complement, using Zariski-VanKampen method. get a presentation of the fundamental group of its complement, using Zariski-VanKampen method.
At some point we expect to have this included in SageMath as an optional (or At some point we expect to have this included in SageMath as an optional (or
maybe even standard) package. When that happens, we will probably provide a maybe even standard) package. When that happens, we will probably provide a
more natural interface for the fundamental group and/or braid monodromy more natural interface for the fundamental group and/or braid monodromy
computation. computation.
## Dependencies: ## Dependencies:
This library deppends on: This library deppends on:
- autotools/libtools/autoconf if you want to generate the configuration - autotools/libtools/autoconf if you want to generate the configuration
scripts (only needed if you get the source code from a git repository) scripts (only needed if you get the source code from a git repository)
- /make/gcc for the build process (you need them to build from a source - /make/gcc for the build process with C++ support (you need them to build from
tarball) a source tarball)
- standard c libraries (math, io and std) - standard c libraries (math, io and std)
- mpfr - mpfr
- gmp - gmp
## Installation: ## Installation:
The following instructions install the library and header files in the standard
system locations. If you want to install it in a different location, you can pass
extra arguments to the configure script.
In particular, if you want to install it so it can be used from a SageMath install
you have to use
```
./configure --prefix=<sagedir>/local --libdir=<sagedir>/local/lib
```
where <sagedir> is the directory where SageMath is installed.
### From the git repository ### From the git repository
You can get the git repository by running You can get the git repository by running
``` ```
git clone https://github.com/miguelmarco/SIROCCO2.git git clone https://github.com/miguelmarco/SIROCCO2.git
``` ```
And then cd in the directory and run And then cd in the directory and run
``` ```
autoreconf --install autoreconf --install
@ -230,7 +243,7 @@ This last line might require superuser privileges for writing in system folders
### From a tar.gz package ### From a tar.gz package
If you got a tarball produced by a `make dist`command, just unpack it and run If you got a tarball produced by a `make dist`command, just unpack it and run
``` ```
./configure ./configure
@ -242,6 +255,6 @@ as before.
## To do: ## To do:
- include an option for passing the factors of the polynomial, for the cases - include an option for passing the factors of the polynomial, for the cases
where the original polynomial is reducible. This might speed up the computations where the original polynomial is reducible. This might speed up the computations