How to use Bertini_real



Bertini_real is command line software. The user's manual is available here. You should use it. These instructions here are woefully incomplete. Use the manual.


Shortly, you call it from the command line, and let it do its thing.

Here's the pattern:

1.
Run Bertini, tracktype: 1;, to produce the Numerical Irreducible Decomposition. This does several things. It produces the witness points, the points on the curve or surface, which we will subsequently track around during bertini_real. It also produces the witness linears which are used in the regeneration and slicing steps of the algorithm. The necessary file for bertini_real is called witness_data.

2.
Verify the output is as you like.

3.
Call Bertini_real, on the command line. You can pass options at run-time, such as the level of screen output, specify a sphere of interest, choose a projection to use, etc. For example, bertini_real -verb 2 -sphere unit_sphere_at_origin -pi my_projection

Bertini_real uses the tracker options for Bertini, which are set at the top of the input file. Suggested options to use for bertini_real include sharpendigits > 0, and imagthreshold ~ 1e-5. Other options can improve performance and tighten up the produced decomposition.

4.
Visualize. In Matlab, call gather_br_samples. This parses the set of output results, into a .mat file. Then, call bertini_real_plotter(), which creates a handle class object and facilitates selection of parts of the decomposition to view, transparency, etc. There are many options, which are documented and displayed via help bertini_real_plotter.

If the results of the decomposition are not satisfactory, changing some settings are in order. The setting imagthreshold is important, as it is used to tell when two found points are distinct from each other. If it is too small, small slices will happen. Another setting which can positively affect decomposition is tracktolbeforeeg, which helps keep paths from crossing, the occurrence of which leads to missing points in the decomposition. It does increase runtime, though, so finding the sweet spot for a particular system can take some experimentation.

Bertini_real is parallel-enabled, using MPI (and in fact, this is required to build the software). To use multiple processors, call it as you would any other MPI program: mpiexec [options] bertini_real.

5.
If you are satisfied with the results of the decomposition, you may wish to refine the triangulation of the surface or curve, and another program sampler is supplied for this purpose. Call it on the command line as with bertini_real, e.g. sampler -fixed 10 to sample each cell to have 10^d samples on it, where d is the dimension of the component.

Adaptive sampling is provided for curves, and is the default mode. Adaptive sampling is not implemented for surfaces. If this is something you want / need, perhaps you would like to start collaborating with the authors of Bertini_real?

6.
Publish your results, and kindly cite Bertini_real!
If you ever want or need help, find bugs, or have criticism, please raise an issue on the github page for this software.