Read Me

Using COCO:

- uncompress the package
- start Matlab
- in Matlab change to coco/toolboxes
- execute startup.m
- change to coco/examples and run the demos

To simplify using coco you might want to execute startup.m whenever Matlab starts. Please see the Matlab documentation for how to do this.

The text below is outdated. There will soon be a paper on the mathematical concepts of the core and we will update the documentation in the M-files of coco.

#####################################################################
This file contains some very basic documentation of ideas fundamental to this package. The ultimate source of reference is still the source code though.



1. The philosophy of the data structure opts
--------------------------------------------

The basic objectives behind the opts structure are to make it easy to replace parts of an algorithm, to avoid the use of global variables or long argument lists and to store the full state of the continuation algorithm in an organised way. For example, it should be possible to replace Newton's method with another algorithm, or the code for 1D continuation with a code for 2D continuation. Also, the user should be able to set certain constants influencing algorithms in a fairly simple way.

The dependencies within individual parts of a continuation code have the form of a graph. This graph may be quite deep and may contain loops (it is not a tree). We represent such a graph as a dictionary, that is, a table with two columns, a class name and a set of values. This table is encoded as a structure and the principal form of access is

  val = opts.class_name.property_name

Now, a class like 'cont' may contain a property named 'corrector', which specifies the corrector to use by the continuation method. It would access functions and properties defined by this corrector with

  corrector = opts.cont.corrector
  opts = opts.(corrector).some_function(opts, ...)

This is similar to pointers and one can exchange the corrector by assigning a non-default value to the property 'corrector' of the class 'cont'. This way it is possible to represent arbitrary graphs with a flat data structure.

You should aim at making it possible to replace algorithms in a transparent way as much as possible. You should pass and return the opts structure in/from any algorithm. Use function definitions like

  function [opts, varargout] = some_function(opts, varargin)

This somewhat strange syntax of having an input and output argument with the same name allows Matlab to optimise access to the structure opts (that is, to avoid any unnecessary copying).



2. The concept of sub-toolboxing
--------------------------------

The idea of sub-toolboxing is to make it possible that any toolbox for some continuation problem can be used as a building block for other toolboxes. Take, as a simple example, the continuation of homoclinic orbits. The classic way to attack this problem is to construct a BVP that contains the equations for the fixed point and its invariant manifolds in the boundary conditions. A more natural way seems to be to combine two toolboxes, one for fixed point continuation with another one for solutions of boundary value problems. These two toolboxes would become sub-toolboxes of a homoclinic orbit toolbox, which in turn is a sub-toolbox for the continuation code.

Toolboxes like MPBVP should be designed keeping this in mind. They should provide a full set of interface functions for constructing and manipulating equations and for accessing all parts of the solution in a well-defined way.

The ideal toolbox does a specific well-defined job and can be replaced by any other toolbox offereing the same interface.

At the moment our toolboxes do not strictly follow this idea as the entry functions with names defined as

  func_name = sprintf('%s_%s2%s', TOOLBOX, FROM_ST, TO_ST)

call Newton's method COCO explicitly. Instead, they should only construct an algorithm in functional form and an initial solution and then return to COCO. This will be one of the more important changes to this package; see the next section for more details.



3. Changes planned in the future
--------------------------------

There are several changes we want to make, which are due to design limitations that we discovered during testing.

We plan to reorganise the finite state machine for the continuation code. The main goal is to split it properly according to functionality. The corrector is already a separate toolbox. Similarly, we will have a rather abstract continuation code and a toolbox representing a manifold. The latter toolbox will become responsible for constructing an apropriate data structure, the construction of extended systems, the prediction and mesh-adaptation (of the mesh of the family of solutions, not the collocation points). The continuation code will be rearranged to work with srbitrary-dimensional families of solutions.

Another major addition is to enable additional constraints and test functions. This is quite complicated and may strongly influence the communication with other toolboxes. As yet it is not clear how we are going to implement this important feature. We aim at making it possible to add constraints and allow the continuation of higher co-dimension curves/families. We also aim at making this independent of the dimension of the family of solutions.

There are a number of other changes that may influence other toolboxes. Please see the file toolbox/todo.txt for a complete list of open problems.