This is the plCurve library, designed for working with piecewise linear
(not necessarily connected) R^3 curves.  It also includes vector-handling
routines and some basic support for spline equivalents of the plCurves.

New in library versions 7.0.1 (and later), this includes the functionality
of the previous octrope library for computing the thickness and ropelength
of polygonal curves. plCurve no longer includes a python interface, as it
proved too difficult to support. 

Installation
============

On Mac OS X 
-----------

1. Install the XCode command line tools: `xcode-select --install`
2. Install Homebrew: Info at http://brew.sh/
3. Install the cantarellalab tap: brew tap designbynumbers/cantarellalab
4. Install plcurve: brew install libplcurve

Alternately, you can install from the source tarball located at

https://www.jasoncantarella.com/downloads/libplcurve-(version).tar.gz

1. Install gsl: `brew install gsl`
2. Install cairo: `brew install cairo`
3. Run configure: `./configure LDFLAGS="-L/usr/local/lib -L/opt/lib -L/opt/homebrew/lib" CPPFLAGS="-I/usr/local/include -I/opt/homebrew/include -I/opt/include"`
4. Make: `make`
5. Run the C tests: `make check`
6. Install: `make install` or possibly `sudo make install`

If you have trouble building the package, and you have previously installed a
version of plcurve on the same (mac) machine, try

`sudo make uninstall`

before making if you problems, particularly with header files. The
build will sometimes pick up old versions of the headers from
/usr/local/include and put them instead of the updated headers in the
package.

On Amazon Linux (such as AWS)
----------------------

1. Install the development tools: `sudo yum groupinstall "Development Tools"`
2. Install gsl: `sudo yum install gsl-devel`
3. Configure: `./configure`
4. Make: `make`
5. Run the C tests: `make check`
6. Install: `sudo make install`

At this point you may need to add /usr/local/lib to the ld path.
8. Create a file `local.conf` in /etc/ld.so.conf.d/ and give it the
one line, `/usr/local/lib`. You need to be SU for this; typically
`sudo nano /etc/ld.so.conf.d/local.conf` is a fine editor command.
9. `sudo ldconfig` to update the ld configuration cache

On Ubuntu Linux 14.04 LTS (also tested on Ubuntu 18.04)
----------------------

0. Update the apt package list: `sudo apt-get update`
1. Install the development tools: `sudo apt-get install build-essential`
2. Install gsl: `sudo apt-get install libgsl0-dev`

At this point you should acquire the source code and `cd` to its directory.

3. Configure: `./configure`
4. Make: `make`
5. Run the C tests: `make check`
6. Install: `sudo make install`
7. `sudo ldconfig` to update the ld configuration cache (to find new libs)

`make check` occasionally failing
=================================

This is okay! There are some random test cases which are run during a
`make check`. We expect the failure rate of `ccode_test` to be under
3%; when this happens there will be a message in
`%BUILD_DIR%/test/ccode_test.log`:

    FAIL
    unable to generate pd code from plcurve
    !! this is *expected* to happen 2.5% of the time
    !! see the README for more information

If you believe that you are seeing this error message more often than
expected, please get in touch with the maintainers. See below for more
details.

We know that there will be some cases in which `randomwalk_test()` (a
test that runs during `ccode_test`) will fail to project to a pdcode
object; principle among reasons are those in which edges of the random
polygon generated are self-intersecting (in which case we would be
unable to determine the sign of that given crossing in constructing
the pdcode object).

Based on a run of the program in `test/randomwalk_test_test.c`, the
expected success rate of a given loop run in randomwalk_test() run on
random polygons with 250 edges is about 999974 in 1000000
(99.9974%). Hence, the expected failure probability of a given random
250-gon is 2.6e-5.

In `ccode_test`, `randomwalk_test()` is called to process 1001 random
250-gons into pdcode objects. If a single loop 'fails', the entire
test 'fails'. Based on the prior run of this program, we estimate (as
of March 2016) that this step should pass about 97.431% of the time,
or fail about 3-in-100 times.