  ***************************************************************************
  * All the software  contained in this library  is protected by copyright. *
  * Permission  to use, copy, modify, and  distribute this software for any *
  * purpose without fee is hereby granted, provided that this entire notice *
  * is included  in all copies  of any software which is or includes a copy *
  * or modification  of this software  and in all copies  of the supporting *
  * documentation for such software.                                        *
  ***************************************************************************
  * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED *
  * WARRANTY. IN NO EVENT, NEITHER  THE AUTHORS, NOR THE PUBLISHER, NOR ANY *
  * MEMBER  OF THE EDITORIAL BOARD OF  THE JOURNAL  "NUMERICAL ALGORITHMS", *
  * NOR ITS EDITOR-IN-CHIEF, BE  LIABLE FOR ANY ERROR  IN THE SOFTWARE, ANY *
  * MISUSE  OF IT  OR ANY DAMAGE ARISING OUT OF ITS USE. THE ENTIRE RISK OF *
  * USING THE SOFTWARE LIES WITH THE PARTY DOING SO.                        *
  ***************************************************************************
  * ANY USE  OF THE SOFTWARE  CONSTITUTES  ACCEPTANCE  OF THE TERMS  OF THE *
  * ABOVE STATEMENT.                                                        *
  ***************************************************************************

   AUTHORS:

       Daniel J. Bates
       Colorado State University, USA
       E-mail: bates@math.colostate.edu

       Andrew J. Newell
       North Carolina State University, USA
       E-mail: andrew_newell@ncsu.edu

       Matthew Niemerg
       UC Berkeley, USA
       E-mail: matthew.niemerg@gmail.com

   REFERENCE:

    -  BertiniLab: A MATLAB interface for solving systems of polynomial
       equations
       NUMERICAL ALGORITHMS, 71 (2016), pp. 229-244

   SOFTWARE REVISION DATE:

       V1.5, April 2015

   SOFTWARE LANGUAGE:

       MATLAB R2012b and later


================================================================================
SOFTWARE
================================================================================

This software provides a MATLAB interface to the numerical homotopy
continuation package Bertini, which solves systems of polynomial equations.
BertiniLab can be used to create input files for Bertini, run Bertini and
process the solutions. All features of Bertini 1.5 are supported. The user
can define the system of equations using a MATLAB numerical function, and
vector and matrix operations are allowed. An object-oriented design allows
the user to separate the statement of the problem from the details of the
solution; the user can create subclasses to provide shortcuts or to tailor
BertiniLab to a specific kind of problem.


================================================================================
PACKAGE
================================================================================

The package contains the following folders:

@BertiniLab      - A class folder: the main engine for running Bertini
@polysym         - A class for symbolic manipulations
doc              - Documentation
examples         - Some examples of using the classes
shortcuts        - Some functions for simple uses of Bertini.
tests            - Unit tests

It also has the utilities BertiniClean, BertiniLabRoot, BertiniLabVersion,
and the file GettingStartedWithBertiniLab.html which gives access to the
documentation system.


================================================================================
HOW TO INSTALL
================================================================================

To install BertiniLab, go to the folder BertiniLab and type the command

install

This adds the BertiniLab folders to the MATLAB path and creates two
utilities, BertiniLabRoot and BertiniLabVersion. It also returns a string
that can be added to the startup.m file so this folder is automatically
added to the path when MATLAB is started. Once this is done, it is not
necessary to install BertiniLab again.

BertiniLab requires an installation of Bertini.
Source code and executables for Bertini can be obtained from the Bertini
home page (https://bertini.nd.edu/). 

To use Bertini on a Mac or a Linux machine, simply download the executable.
On a PC, it must be compiled on Cygwin (see the installation instructions
that come with the package). Then locate the following dynamic libraries
and copy them to the folder that the Bertini executable resides in:

cygwin1.dll
cygcc*.dll
cyggmp*.dll
cygmpfr*.dll

(the stars represent characters that will depend on the version of cygwin
installed).

BertiniLab needs to be told where Bertini is by doing the following:

1. Open @BertiniLab/BertiniLab.m.
2. Edit the line program_folder = '/usr/local/bin'; to provide the folder
   where bertini resides.
3. Edit the line program_name = 'bertini'; to provide the name that is used
   to call Bertini.

When you install Bertini in Cygwin, you provide a Unix address for the
installation, for example, /usr/local/bin/bertini. This must be converted
to its Windows address by changing the forward slashes to backward slashes
and appending it to the name of the Cygwin folder, for example,
C:\cygwin64\usr\local\bin\bertini.


================================================================================
TEST
================================================================================

BertiniLab was tested on Matlab R2012b, R2013a, 2014a and 2014b. A suite of
unit tests are included in the tests folder. For 2013a and later, the tests
use the MATLAB Unit Test Framework. The command runAllTests, at the base of
the tests folder, runs all the tests. The user can also visit a particular
test folder and type runtests(pwd) to run all the tests in that folder. For
more information on the framework, see the MATLAB documentation (type:
docsearch('Unit Testing Framework'))

For earlier versions, there is a suite of tests in the subfolder R2012 and
earlier. These require the MATLAB xUnit Test Framework by Steve Eddings.
This package can be downloaded from MATLAB Central
(https://www.mathworks.com/matlabcentral/fileexchange/22846-matlab-xunit-test-framework).


================================================================================
FOR FURTHER INFORMATION
================================================================================

View GettingStartedWithBertiniLab.html in a web browser.
On a MATLAB desktop, you can go to the BertiniLab folder and double click
on GettingStartedWithBertiniLab.html.

To view the documentation, open the home page for MATLAB help ('doc'). 
In R2015a or later, the link 'BertiniLab Toolbox' will appear on the bottom 
right under 'Supplemental Software'. In earlier versions, click on the 
'Supplemental Software' button and then on 'BertiniLab Toolbox'.

A suite of examples can be accessed either in the example folder or issuing
the command 'demo toolbox BertiniLab'. It can also be accessed from the
documentation page (see above).

If either the documentation or the examples are not working properly, try
taking BertiniLab off the MATLAB path and putting it back on.

The main source of information on Bertini is the book "Numerically solving 
polynomial systems with Bertini" by Daniel J. Bates, Jonathan D. Haunstein, 
Andrew J. Sommese and Charles W. Wampler (SIAM 2013).

