- Points and Pointsets are enhanced arrays
- Labelling
- Coordinate access and manipulation
- Implementation details
- Point arithmetic and comparison
1. Points and Pointsets are enhanced arrays
The Point and Pointset classes are essentially enhanced Numpy array classes. The primary goal of these two classes is to free the user from dealing with explicit array indices when manipulating scientific or numerically-computed data which are commonly most naturally referenced by names. We believe the "index free" array is a liberating substrate for users, that permits construction of sophisticated computations without the tedious book-keeping of arbitrary integer array indices. This comes at little cost to efficiency, especially as regular arrays can easily be extracted from a Pointset or reassembled into one, so that data porting to other applications is easy.
Pointsets may either be parameterized by an independent variable -- in which case they are callable with values of that variable, or they may be non-parameterized -- in which case they are not callable. In either case they can be referenced by array index, or in other ways (see below).
The display of point and pointset contents uses a numerical precision of 8 significant figures. This cannot be changed by the user, who should extract a subset of the pointset as an array in order to see the values at full precision. Of course, arithmetic comparisons using pointset values use full precision.
2. Labelling
A further feature of Points and Pointsets is their inherent point labelling system, which can be queried and manipulated much like a dictionary, as a way to organize sophisticated access to array data. For instance, this becomes especially useful when exploring the bifurcation sets of a dynamical system using PyCont.
In a Pointset, denoted w, labels are stored by index. To see which point is labelled at index i, look at w[i]. To find out which index corresponds to an independent variable value t, call w.findIndex(t) (parameterized pointsets only). If the value of t is not in the pointset then a pair will be returned that indicates where t lies with respect to existing independent variable values in w.
To see which points in a pointset possess a given string label s, use w.bylabel(s).
Labels should be added and removed using the addlabel and removelabel methods.
Additionally, a pointset may be given a name, which resides in the attribute name.
3. Coordinate access and manipulation
The displayed order of point or pointset coordinates is alphabetical. This is the only supported ordering of coordinates, and also provides the ordering for exported arrays from these objects.
A point can be called and referenced by coordinate name or index.
A point can be removed, appended, or inserted into a pointset using the methods remove, append and insert. Note that, unlike with lists, you can append either an individual point or a pointset object. A method named extend is also provided, and has identical functionality to append.
A parameterized pointset can be called at a specific independent variable value (or set of values), with an additional argument to select coordinates in the output. A pointset can be referenced by point index (returning a point), a set of indices (returning a pointset corresponding to points at those indices), or by coordinate name (returning a pointset containing only that coordinate at all point indices). The bylabel method also allows points to be selected based on their label.
Both points and pointsets can have their values set in the same ways that both a dictionary and a list can be.
The full range of possibilities in the point and pointset interface can be seen by running the Points.py file as a script and reading the examples in the output.
Pointsets can be reversed in place using the reverse method.
4. Implementation details
Unlabelled points and unlabelled non-parameterized pointsets can be created by calling the appropriate class constructor with a dictionary mapping coordinate name keys to numeric or array/list values.
Points and pointsets can have their values (i.e. not including the independent variable, if present) turned into a dictionary by calling the in-built function dict with the point or pointset as argument. A todict method is also implemented.
The Point class is defined to closely resemble a mapping object class such as dict (although it is not a subtype of dict). Pointset is a subclass of Point, although it acts more like a list than a dictionary. Most natural operations for dictionaries and lists apply equally to the respective subclasses.
5. Point arithmetic and comparison
Basic arithmetic and comparison operations can be performed on Points and Pointsets, in much the same way as can be done with arrays. The ordering and test of equality for points is defined according to the choice of norm for the points. By default, this is L2 norm, although this can be changed using the 'norm' key in the argument dictionary at initialization to be values from 1 to Inf. Comparison of both points and pointsets using the usual arithmetic operators will compare objects point-wise based on their norms.
To compare two points or pointsets, coordinate for coordinate, use the comparePointCoords function (which also accepts appropriately keyed dictionaries). The comparison can be made stricter using the optional fussy boolean argument, in which case the norm and coordinate type are also checked for equality, provided only points and pointsets are passed to the function.
Points can be compared to single values, returning a Boolean array that indicate matching coordinates (ordered). Similarly, Pointsets can be compared to Points, returning a Boolean array indicating matching positions. This functionality is much like that of Numpy arrays.