***************************************************************************************************
* Krystals Schema *
* Version 2.1 copyright James Ingram 2008, 2022 *
* *
* Defines the following elements and subtypes: *
* *
* Elements: *
* 1 krystal: The root element of a krystal (.krys) file. *
* Contains heredity info, and strands. *
* 2 expander: The root element of an expander (.kexp) file. *
* Contains input and output gametes, or the name(s) of the expander(s) where the definition *
* of each gamete can be found. *
* 3 modulator: The root element of a modulator (.kmod) file. *
* Contains a two dimensional array of unsigned integers. *
* *
* Complex Types: *
* 1 strand: a krystal component. *
* has a level and a stringOfUnsignedInts *
* 2 gamete: an expander component. *
* Contains lists of pointGroups (fixed points and planets). *
* *
* Simple Types: *
* 1 stringOfUnsignedInts: a component of strands and modulators *
* Is a string of unsignedInts separated by whitespace *
* 2 pointGroup: a gamete component *
* Is a description of a group of points. *
* *
* File Name Types: *
* 1 krystalName: A name meaning any type of krystal (.krys) *
* 2. expanderName: The name of an expander (.kexp) file *
* 3. modulatorName: The name of a modulator (.kmod) file *
* 4. pathKrystalSVGSourceName: The SVG source for a path krystal (.svg) *
***************************************************************************************************
A constant krystal's strand has level=0, and contains its (one) value.
A line krystal's strand has level=1, and contains its value (stringOfUnsignedInt).
density: the name of a krystal file containing the density of each strand
(each moment) in this krystal. (A constant density produces a level 1
krystal whose strand has the given constant number of values.)
inputPoints: the name of a krystal file containing the name of the gamete
input point for each strand in this krystal.
For contoured expansions only, the following two input krystals define the contours.
If one is present, then both must be present:
axis: the name of a krystal file containing axis values in range 1..12
contour: the name of a krystal file containing contour number values in range 1..12
expander: the name of a .kexp file containing the expander (expansion
field) for this krystal.
x: The name of a krystal file containing the x-coordinate values for the
modulator.
y: The name of a krystal file containing the y-coordinate values for the
modulator.
modulator: The name of a modulator file.
source: The name of a krystal file to be permuted.
axis: The name of a krystal file containing the axis coordinates for the permutation.
contour: The name of a krystal file containing the contour coordinates for the permutation.
pLevel: An integer which sets the level of the permutation.
sortFirst: true if the source values sorted into ascending order before applying the permutation.
svg: an SVG file, edited to contain field and trajectory info.
density: the name of a krystal file containing the density of each strand in this krystal.
(A constant density produces a level 1 krystal whose strand has the given constant number of values.)
Strand(s) values are unsigned integers separated by white-space. For example:
The level (l) attribute is 0 for constant krystals, but otherwise in the range
1..unlimited. A constant krystal has a single strand with level=0 containing a
single unsigned integer. Otherwise, the first strand must have level 1. This is
then the *only* level 1 strand in the krystal. The level values describe the
krystal's tree structure.
A strand is a krystal component consisting of a stringOfUnsignedInts with a level attribute.
The level (l) attribute is 0 in constant krystals but otherwise in the range 1..unlimited.
A constant krystal has a single strand with level=0 containing a single integer value.
Otherwise, the first strand in a krystal must have level 1, and this is the *only* level 1 strand.
The level values describe the krystal's tree structure. To save space (there may be very many
strands), the krystal element defines strand names to be 's', so a strand looks something like:
pointGroups are used by both fixedPoints and planet elements in gametes.
In both fixed and planet circular pointGroups, the 'to' element is identical to the "from" element,
and the points are distributed evenly around the circle starting at the "from" coordinate.
Otherwise, all fixed (non-circular) pointGroups have points at both their 'from' and 'to'
coordinates.
However, planet pointGroups are contiguous. ONLY THE FINAL POINTGROUP of a planet has a point at its
'to' coordinate.
The 'value' of a fixedPoints pointGroup contains as many unsigned integers as there are points, while
planets have one value each. A planet's value is stored in each of its subpaths (pointGroups).
For example:
A modulatorArray is a modulator component consisting of a stringOfUnsignedInts with xdim and ydim
attributes.
A stringOfUnsignedInts contains a string of 1 or more unsignedInts and whitespace.
The string may not be empty.
In XML files, the string can be formatted with any kinds of whitespace. For example:
constant, line, path, mod, perm Krystal names have the following form:
[domain].[shape].[index].[type].krys
expansion and shaped expansion Krystal names have the following form:
[domain].[shape].[expanderID].[index].[type].krys
The components are separated by '.' characters, and:
[domain] is the maximum value of any value in the krystal.
[shape] contains one or more integers separated by '_' characters.
The first int in the [shape] is the number of level 1 and level 2 strands, so:
"0" is a constant krystal -- containing one strand having level 0 and one value (=domain) (no level 1 or level 2 strands).
"1_[nValues]" is a line krystal -- containing one strand having level 1 and [nValues] values (no level 2 strands).
"7_[nValues)" is a level 2 krystal -- containing 7 strands (1 level 1 and 6 level 2 strands) and [nValues] values.
"7_28_[nValues]" is a level 3 krystal - containing 28 strands having level 1, 2, or 3, and [nValues] values.
"7_28_206_[nValues]" is a level 4 krystal - containing 206 strands having level 1, 2, 3 or 4, and [nValues] values.
[expanderID] is a unique identifier for the expander being used in either the exp or shaped krystal.
This is the 3rd integer in the expanderName (see below)
[index] is an identifier that makes the krystal's name unique in the krystals folder.
[type] is a string identifying the krystal's type (and therefore heredity information).
Expander names have the following form:
[nInputPoints].[nFoci].[id].kexp
The components are separated by '.' characters, and:
component[0] is the number of expansion points (input gamete)
component[1] is the number of focus points (output gamete)
component[2] is the file's unique id. This is a different integer for each Expander in the expanders folder.
.kexp is the file extension for an expander.
Examples: "7.7.1.kexp", "7.7.3.kexp", "7.7.97.kexp"
Modulator names have the following form:
[xDim].[yDim].[maxVal].[index].kmod
Example: "5.4.240.1.kmod"
The components are separated by '.' characters, and:
component[0] is the size of the x-dimension
component[1] is the size of the y-dimension
component[2] is the largest value in the modulator
component[3] is the file's unique index. This is a different integer for each Modulator in the modulators folder.
.kmod is the file extension for a modulator.
The name of an .svg file containing information for a path krystal:
[n field points (=domain)].[n trajectory points].[index].path.svg
For example: 12.7.1.path.svg, 12.113.2.path.svg
Note that the filename can stipulate that the number of trajectory
points is 1, even though the minimum number of nodes in a trajectory path is
actually 2. If this is done, only the first node in the "trajectory" will be used,
so that it is effectively a constant.