API reference

Pose{D,F,R<:Rotation{D,F}}

A Pose describes the configuration of a D-dimensional rigid body. It consists of translational coordinates pose.x and orientational coordinates pose.psi.

dimension(p::ParticleSpecies)

Return the spatial dimension a particle of species p lives in.

dimension(::BindingRules)

Return the spatial dimension of the particles of the assembly system rules.

numtype(::ParticleSpecies)

Return the numeric element type, derived from the BindingSite type parameter.

posetype(::ParticleSpecies)

Return the concrete Pose type used by the particle species.

sitetype(rules::BindingRules)

The concrete BindingSite type of every site in rules, for sizing a container that holds them.

sitetype(p::AbstractPolyform)

The concrete BindingSite type of every site of p, for sizing a container that holds them.

particletype(rules::BindingRules)

The concrete Particle type of every particle in a Polyform of rules, for sizing a container that holds them.

particletype(p::AbstractPolyform)

The concrete Particle type of every particle in p, for sizing a container that holds them.

BindingSite{P<:Pose}

A BindingSite describes an anchor point at which particles are attached together. The binding site color, together with an interaction matrix, determines whether two binding sites may bind.

sitesym is the order of the site's own rotational symmetry about its outward normal, disregarding the rest of the particle. stab size of the stabilizer of this site in the rotational symmetry group of the containing particle. For example, consider a square side of a 3-prism (i.e. an extruded triangle). The side has 4-fold symmetry (sitesym == 4), but only two of these rotations are symmetries of the entire particle (stab == 2).

A binding site's pose carries three things. Its position and its outward normal (the pose's local x axis) are physical. The remaining freedom in the frame, the twist, is generally not: a site with a sitesym-fold symmetry is unchanged by turns of 2π/sitesym about its normal, so psi, psi·Rx(2π/sitesym), ... all describe the same site.

locking determines if the binding site fixes the twist between it and its binding partners. A locking site holds its partner fixed in the relative orientation defined by its frame (see standard_twist), up to symmetry transformations of the particle, so the number of the possible twists is equal to stab. If locking==false, the site allows all twists that are compatible with the site symmetry alone, disregarding the symmetry of the particle, so the number of twists is equal to sitesym. The two choices of locking coincide whenever the stabilizer of the site is equal to its individual symmetry group.

color(b::BindingSite)

Return the binding site's color.

If the binding site comes from an BindingRules, its interactions with other binding sites are determined by interactionmatrix(rules)[:, color(b)].

color(rules::BindingRules, loc::SpeciesSiteLoc)

Return the interaction color of the binding site loc names.

twistfreedom(b::BindingSite)

Return how many possible twists binding site b allows. Equal to stab if the site is locking, and equal to sitesym otherwise. See BindingSite.

twistfreedom(b1::BindingSite, b2::BindingSite)

Return ntwists, the number of twists about the bond axis that a bond between b1 and b2 admits. Equal to the least common multiple of the two sites' own twist freedoms, since the admissible set has to be closed under both. See standard_twist.

twist(b1::BindingSite, b2::BindingSite)

Return which of the bond's twists the two sites are in, or nothing if their orientations are not related by any of them.

This function is symmetric in its arguments.

standard_twist(b::BindingSite, t=0, ntwists=1)
standard_twist(p::Pose, t=0, ntwists=1)

Return the pose a partner of binding site b takes when the bond is in twist t of ntwists.

We employ the convention that attached binding sites are "facing each other": their poses are related via a 180 degree rotation around their (shared) z-axes.

A bond in 3D additionally admits a twist about the bond (x-)axis. This twist is generally fixed by the two sites' frames, except that the frame of a symmetric particle can only be determined up to symmetry transformations. If there are ntwists admissable twists, then any twist angle that is a multiple of 2π/ntwists is valid, and t indexes them from 0.

Contact(vs1, vs2, twist, ntwists)

Two binding sites found in contact, and how they meet.

vs1 and vs2 are the graphrep vertex ranges the two sites occupy. twist is which of the ntwists twists the bond admits they are in. See also contact_pairing,

contact_pairing(vs1::UnitRange, vs2::UnitRange, t=0, ntwists=1)

Return the pairs of graph vertices that should be joined when two bonding binding sites occupying the vertex ranges vs1 and vs2 meet in twist t of ntwists (see standard_twist).

Imagine the vertices corresponds to corners of a regular n-gon attached to the site, number the vertices of each site starting from zero and denote kᵢ = length(vsᵢ). Vertex a of site 1 then sits at angle 2πa/k₁ in site 1's frame, and vertex b of site 2 (whose frame is turned by 2πt/ntwists and then flipped, so its cyclic order runs the other way around) sits at 2πt/ntwists - 2πb/k₂. Writing K = lcm(k₁, k₂), s₁ = K/k₁, s₂ = K/k₂, the coincidences are the solutions of

a*s₁ + b*s₂ = m   (mod K),      m = t*K/ntwists

m is always an integer: a site's sitesym gᵢ divides its vertex count, so ntwists = lcm(g₁, g₂) divides K. Since gcd(s₁, s₂) = 1, the congruence has exactly gcd(k₁, k₂) solutions for every m, and distinct twists give disjoint solution sets, so the pairing count never depends on the twist, and the graph records which twist a bond is in.

Polyhedron{F}

A convex polyhedron, stored as a list of corners (vertices) and a list of faces.

Each face is a list of indices into corners, wound counter-clockwise as seen from outside the body. This winding is what fixes the orientation of the graph encoding. On construction, each face is rotated to start at a canonical corner.

corners(p::Polyhedron)

Return the corner positions of p.

faces(p::Polyhedron)

Return the faces of p as lists of corner indices, each wound counter-clockwise seen from outside.

facevertices(p::Polyhedron, i)

Return the corner indices of the ith face of p.

nfaces(p::Polyhedron)

Return the number of faces of p.

nedges(p::Polyhedron)

Return the number of edges of p.

facecentroid(p::Polyhedron, i)

Return the centroid of the ith face of p.

facenormal(p::Polyhedron, i)

Return the outward unit normal of the ith face of p.

edgemidpoint(p::Polyhedron, i, k)

Return the midpoint of edge k of face i of p.

minedgelength(p::Polyhedron)

Return the length of the shortest edge of p.

inradius(p::Polyhedron)

Return the distance from the origin to the closest face centroid of p.

rotationgroup(p::Polyhedron)

Return the rotations that map p onto itself, as RotMatrix3es about the corner centroid.

rotationgroup(ps::ParticleSpecies)

Return the rotational symmetry group of ps as rotations about the particle origin: those that map every binding site onto a site with the same symmetry label, matching orientation as well as position.

The counterpart of permutationgroup, which returns the same group as site permutations.

faceorbits(p::Polyhedron)

Group the faces into the orbits of rotationgroup, and return one orbit index per face.

Passing these to dartencoding yields the body's true rotation group, whereas labels=fill(1, nfaces(p)) yields the combinatorial symmetry of the face lattice, which can be larger. For example, Pyramid(3) is combinatorially a tetrahedron and would report 12 instead of its actual 3.

facesym(p::Polyhedron, i)
facesym(p::Polyhedron)

Return the order of face i's own rotational symmetry about its outward normal.

This is the sitesym of a binding site placed on that face: a face invariant under turns of 2π/sitesym has that many equally good twist references, so nothing about the particle in isolation may depend on which was picked. It divides the face degree and equals it only for a regular face; a rectangular face has degree 4 but only 2-fold symmetry.

It is a property of the face alone, not of the body it belongs to. A triangular prism is only 2-fold about a square side face, but the face is still a square, so facesym is 4 there.

siteorbits(poses, sitesyms, colors; group=nothing)

Group the sites into the orbits of the rotations that preserve the colored arrangement, and return one orbit index per site.

sitelabel(ps::ParticleSpecies, i::Integer)

Return the symmetry label of site i of ps, the graph label all of that site's vertices carry.

permutationgroup(ps::ParticleSpecies)

Return the rotational symmetry group of ps as site permutations: one permutation per rotation about the particle origin that maps every binding site onto a site with the same symmetry label, matching orientation as well as position.

The counterpart of rotationgroup, which returns the same group as rotations. Compare symmetrynumber, which reads the order of this group off the graph encoding instead; check_encoding is the check that the two agree.

permutationgroup(p::Polyform)

Return the rotational symmetry group of p as particle permutations: one permutation per rotation about the centroid of p's particle positions that carries every particle onto a particle of the same species, matching position and orientation.

The counterpart of rotationgroup(::Polyform), which returns the same group as rotations, and the assembled analogue of permutationgroup(::ParticleSpecies), which permutes a single particle's sites.

length(permutationgroup(p)) should equal symmetrynumber(p), which reads the same order off the graph encoding. Use it to check an encoding rather than to compute the symmetry number, which nauty gives far more cheaply.

The list holds one entry per rotation, so it may repeat: the action on particles is not faithful. A straight chain of cubes turned about the chain axis leaves every particle where it was and still moves the graph. Call unique on the result for the quotient group.

check_encoding(ps::ParticleSpecies)

Throw if ps's graph claims a different symmetry from its geometry and colors, or if its labeling is not exactly its symmetry orbits. Return ps.

Three things have to agree:

1. the labeling is at least as fine as the coloring, and is exactly the symmetry orbits
2. the graph's automorphism group and the geometry's rotation group have the same order
3. they also have the same orbits, since two groups of equal order can act differently

Every built-in species runs this in its constructor. Call it in your own if you write graph labels by hand instead of deriving them with siteorbits.

stabilizerorders(ps::ParticleSpecies)

Return the order of each site's stabilizer: how many of the particle's own symmetries leave the site where it is.

stabilizerorders(poses, sitesyms, sitelabels; group=nothing)

Return the order of each site's stabilizer: how many of the particle's own symmetries leave the site where it is.

dartencoding(p::Polyhedron; labels=1:nfaces(p))
dartencoding(faces::Vector{Vector{Int}}; labels=1:length(faces))

Return (g, ranges), the dart encoding of polyhedron p and the graph vertices belonging to each face.

A dart is a half-edge: one of the two directed traversals of a polyhedron edge, the one belonging to a given face. Each edge therefore has two darts, one per adjoining face, a face of degree k owns k of them, and the dart encoding graph has 2 * nedges(p) vertices in total. The encoding consists of

1. a directed k-cycle through each face's own darts, following the face's counter-clockwise winding, and
2. a bidirectional edge joining the two darts that sit on each shared polyhedron edge.

The automorphism group of the resulting g is the polyhedron's rotational symmetry group. labels assigns one symmetry label per face, inherited by that face's darts: all labels distinct gives a symmetry number of 1, all labels equal gives the full rotation group, and merging some faces gives the subgroup preserving that labeling. The dart encoding is closely related to the Cayley graph of the body's symmetry group.

cycleencoding(nsites; labels=1:nsites)

Return (g, ranges), the cycle encoding of a particle with nsites binding sites: a single directed cycle carrying one vertex per site.

This is the 2D polygon encoding. It is also valid in 3D when every site's twist freedom is 1 and all labels are distinct, and not otherwise.

RotationGroup

A proper (or chiral) point group: the rotations carrying a rigid body onto itself, without reflections.

The five families are Cyclic, Dihedral, Tetrahedral, Octahedral and Icosahedral. Use rotationgroup to get the rotational symmetries of a body.

Cyclic(n)

The rotation group C_n: n turns about a single axis. Order n, realized by Pyramid.

Dihedral(n)

The rotation group D_n: the n turns about a principal axis together with the n half turns about axes perpendicular to it. Order 2n, realized by Prism and Antiprism.

Tetrahedral()

The rotation group T of a regular tetrahedron, of order 12.

Octahedral()

The rotation group O shared by the cube and the regular octahedron, of order 24.

Icosahedral()

The rotation group I shared by the regular dodecahedron and icosahedron, of order 60.

grouporder(group::RotationGroup)

Return the number of elements in group.

Tetrahedron(a=1.0)

A regular tetrahedron with edge length a. Proper rotation group T, of order 12.

Cube(a=1.0)

A cube with edge length a. Proper rotation group O, of order 24.

Octahedron(a=1.0)

A regular octahedron with edge length a. Proper rotation group O, of order 24.

Dodecahedron(a=1.0)

A regular dodecahedron with edge length a. Proper rotation group I, of order 60.

Icosahedron(a=1.0)

A regular icosahedron with edge length a. Proper rotation group I, of order 60.

Pyramid(n, a=1.0; h=a)

A pyramid over a regular n-gon with edge length a and apex height h. Proper rotation group C_n, of order n.

Prism(n, a=1.0; h=a)

A prism over a regular n-gon with edge length a and height h. Proper rotation group D_n, of order 2n. Prism(4) is a cube.

Antiprism(n, a=1.0)

A uniform antiprism over a regular n-gon with edge length a. Proper rotation group D_n, of order 2n. Antiprism(3) is an octahedron.

ParticleSpecies{D,B<:BindingSite}

Abstract supertype of all particle species in D spatial dimensions.

SpeciesAndPose{SPC}

A species paired with a placement, species => pose.

Use this type when writing methods for overlap and could_contact.

bindingsite(p::ParticleSpecies, i::Integer)

Return the ith binding site of particle species p.

bindingsites(p::ParticleSpecies)

Return an iterator over all binding sites of a particle of species p.

bindingsites(p::Particle, rules::BindingRules)

Return an iterator over the binding sites of particle p.

bindingsites(p::AbstractPolyform)

Return a lazy iterator over all binding sites of p, counting through p's particles in the order they are stored and through each particle's own sites, exactly as on a ParticleSpecies.

The ordering depends on how p was assembled. Use canonbindingsite for iterating through binding sites in canonical order.

nsites(p::ParticleSpecies)

Return the number of binding sites of a particle of species p.

graphrep(p::ParticleSpecies)

Return the graph representation of the particle species p.

isconvex(::ParticleSpecies)

Return true if the particle species has a convex shape, which enables minor optimizations when checking for overlaps.

isconvex(p::Particle, rules::BindingRules)

Return true if the particle has a convex shape, which enables minor optimizations when checking for overlaps.

setcolors!(p::ParticleSpecies, colors::AbstractVector{<:Integer})

Assign colors to the binding sites of particle species p.

symmetrynumber(p::ParticleSpecies)

Return the symmetry number of the particle species p.

The symmetry number is equal to the size of the automorphism group of graphrep(p).

symmetrynumber(p::AbstractPolyform)

Return the symmetry number of p, i.e. the size of its automorphism group.

bounding_radius(p::ParticleSpecies)

Return the radius of a bounding sphere centerd at the particle's pose origin.

could_contact(p1::SpeciesAndPose, p2::SpeciesAndPose)

Return true if the particle species at their respective poses could potentially be in contact.

This should be a quick and efficient pre-check; a value of true does not necessarily mean that contact has occured. If false, however, it is assumed that contact is impossible and no further contact checks will be performed.

could_contact(p1::Particle, p2::Particle, rules::BindingRules)

Return true if the particles could potentially be in contact.

overlap(p1::SpeciesAndPose, p2::SpeciesAndPose)

Return true if the particle species at their respective poses are overlapping.

sat_overlap(axes, corners1, pose1, corners2, pose2, skin)

Return true unless some axis in axes separates the two convex bodies, i.e. true if they overlap, with a skin of clearance counting as separated.

Two convex bodies are disjoint exactly when some axis exists on which their projections do not overlap, and it is enough to test a finite candidate set. In 2D the edge normals of both polygons suffice. In 3D it takes both solids' face normals and the cross products of their edge directions, which catch the edge-on-edge configurations no face normal separates.

Axes need not be normalized: each axis is scaled, and degenerate ones (e.g. from parallel edges) are skipped.

edgenormals(corners, pose)

The normals of a 2D polygon's edges, in world coordinates: candidate separating axes for sat_overlap. Only the direction matters, so the sign is not fixed.

PolygonParticleSpecies{F}

A 2D convex regular polygon with n edges and one binding site per edge.

UnitNgon(n, a=1.0; kwargs...)

A regular n-gon with edge length a, with one binding site per edge. Rotation group C_n.

Spelled to match UnitPrism and the other body constructors; it is PolygonParticleSpecies under a name that reads the same way.

UnitTriangle

An equilateral triangle with unit-length edges and one binding site per edge.

UnitSquare

A square with unit-length edges and one binding site per edge.

UnitHexagon

A regular hexagon with unit-length edges and one binding site per edge.

SymmetricUnitTriangle

An equilateral triangle with unit-length edges, every edge the same color.

Where UnitTriangle gives each edge a color of its own, this one leaves the body its full rotation group, so symmetrynumber is 3 rather than 1 and edges bond interchangeably.

SymmetricUnitSquare

A square with unit-length edges, every edge the same color.

Where UnitSquare gives each edge a color of its own, this one leaves the body its full rotation group, so symmetrynumber is 4 rather than 1 and edges bond interchangeably.

SymmetricUnitHexagon

A regular hexagon with unit-length edges, every edge the same color.

Where UnitHexagon gives each edge a color of its own, this one leaves the body its full rotation group, so symmetrynumber is 6 rather than 1 and edges bond interchangeably.

PolyhedronParticleSpecies{F}

A 3D convex polyhedron with one binding site per face.

polyhedron(ps::PolyhedronParticleSpecies)

Return the Polyhedron the species was built from.

UnitTetrahedron

A regular tetrahedron with unit-length edges and one binding site per face.

UnitCube

A cube with unit-length edges and one binding site per face.

UnitOctahedron

A regular octahedron with unit-length edges and one binding site per face.

UnitDodecahedron

A regular dodecahedron with unit-length edges and one binding site per face.

UnitIcosahedron

A regular icosahedron with unit-length edges and one binding site per face.

SymmetricUnitTetrahedron

A regular tetrahedron with unit-length edges, every face the same color.

Where UnitTetrahedron gives each face a color of its own, this one leaves the body its full rotation group, so symmetrynumber reports that group's order rather than 1 and faces bond interchangeably.

SymmetricUnitCube

A cube with unit-length edges, every face the same color.

Where UnitCube gives each face a color of its own, this one leaves the body its full rotation group, so symmetrynumber reports that group's order rather than 1 and faces bond interchangeably.

SymmetricUnitOctahedron

A regular octahedron with unit-length edges, every face the same color.

Where UnitOctahedron gives each face a color of its own, this one leaves the body its full rotation group, so symmetrynumber reports that group's order rather than 1 and faces bond interchangeably.

SymmetricUnitDodecahedron

A regular dodecahedron with unit-length edges, every face the same color.

Where UnitDodecahedron gives each face a color of its own, this one leaves the body its full rotation group, so symmetrynumber reports that group's order rather than 1 and faces bond interchangeably.

SymmetricUnitIcosahedron

A regular icosahedron with unit-length edges, every face the same color.

Where UnitIcosahedron gives each face a color of its own, this one leaves the body its full rotation group, so symmetrynumber reports that group's order rather than 1 and faces bond interchangeably.

UnitPyramid(n, a=1.0; h=a, kwargs...)

A pyramid over a regular n-gon with edge length a, with one binding site per face. Rotation group C_n.

UnitPrism(n, a=1.0; h=a, kwargs...)

A prism over a regular n-gon with edge length a, with one binding site per face. Rotation group D_n, except for UnitPrism(4) whose default height makes it a cube.

UnitAntiprism(n, a=1.0; kwargs...)

A uniform antiprism over a regular n-gon with edge length a, with one binding site per face. Rotation group D_n, except for UnitAntiprism(3) which is a regular octahedron.

PatchyParticleSpecies{D,F,B}

A D-dimensional sphere of radius r with binding sites on its surface.

PatchyDisk(angles, r=1; colors=1:length(angles))

A 2D disk of radius r with one binding site placed at each angle in angles (radians, measured counterclockwise from the +x axis).

PatchySphere(p::Polyhedron, r=1; colors=1:nfaces(p), locking=true, twists=0)

A 3D sphere of radius r carrying one patch per face of polyhedron p, so that the patches inherit the polyhedron's rotation group.

See PolyhedronParticleSpecies for documentation of the keyword arguments.

BindingRules(bonds, particlespecies)

BindingRules consists of a list of particle species and their allowed bonds.

The binding rules are specified by the matrix bonds, where every row of the matrix defines a valid bond between particle species. A bonds is specified in the format [species1 site1 species2 site2]. For example, if binding site 3 of particle species 1 binds to site 4 of particle species 2, the corresponding bond would read [1 3 2 4;]. The ordering of binding sites depends on the specific particle species.

SpeciesSiteLoc(species, site)

Which binding site of which particle species: the address a set of BindingRules speaks in, fixed when the rules are written.

Distinct from ParticleSiteLoc, which names a site of one particle inside a Polyform. Both were NTuple{2,Int} once, so nothing stopped handing one to a function expecting the other.

Iterates and indexes like the pair it replaces, so (s, k) = loc still works.

interactionmatrix(rules::BindingRules)

Return the interaction matrix of the assembly system rules.

The interaction matrix is indexed by the colors of binding sites. If two binding sites have colors c1 and c2, then the truth value of interactionmatrix(rules)[c1, c2] determines whether the two sites are able to bind to each other.

nspecies(rules::BindingRules)

Return the number of particle species of the assembly system rules.

nbonds(rules::BindingRules)

Return the total number of possible bonds between binding sites of the assembly system rules.

nbonds(p::AbstractPolyform)

Return the number of bonds in p. Note that nbonds(::BindingRules) instead counts how many kinds of bond a set of rules allows.

ncolors(rules::BindingRules)

Return the total number of binding sites colors across all particle species of the assembly system rules.

ncolors(rules) is not necessarily the equal to nsites(rules). If particle species have symmetry, some binding sites may carry the same color.

species(rules::BindingRules)

Return the list of particle species of the assembly system rules.

species(rules::BindingRules, i::Integer)

Return the ith particle species of the assembly system rules.

bonded_colors(rules::BindingRules)

Return all pairs of binding site colors that may bind according to the binding rules of the assembly system rules.

bonded_sites(rules::BindingRules)

Return all pairs of binding site locations that may bind according to the binding rules of the assembly system rules.

bonded_species(rules::BindingRules)

Return all pairs of particle species that may bind according to the binding rules of the assembly system rules.

isinert(rules::BindingRules, loc::SpeciesSiteLoc)

Return true if the binding site loc names binds to nothing.

isinert(rules::BindingRules, color::Integer)

Return true if the binding site with color color does not bind to any binding sites.

AbstractPolyform{D}

An aggregate of particles in D dimensions, connected at binding sites and represented by a directed graph.

Polyform

A Polyform is an aggregate of particles connected at binding sites, represented by a directed graph.

ParticleSiteLoc(particle, site)

Which binding site of which particle inside a Polyform: where a site actually is in an assembled structure.

Distinct from SpeciesSiteLoc, which names a site of a species and is what a set of BindingRules speaks in. Both were NTuple{2,Int} once.

Iterates and indexes like the pair it replaces, so (p, k) = ps still works.

nparticles(p::AbstractPolyform)

Return the number of particles in p.

bindingrules(p::AbstractPolyform)

Return the BindingRules that p belongs to.

composition(p::AbstractPolyform)

Return the composition vector of p: counts of each particle species (indices 1:nspecies(rules)) followed by counts of each bond type (indices nspecies+1:end). Bond types are ordered as in bonded_colors(bindingrules(p)).

canonbindingsite(p::AbstractPolyform, i::Integer)

Return the i-th binding site of p in canonical order, which follows the canonical graph labeling and is therefore the same for any two isomorphic polyforms.

canonbindingsites(p::AbstractPolyform)

Return a lazy iterator over all binding sites of p in canonical order.

exposedsites(poly::AbstractPolyform)

The BindingSite of every unbound site of poly, in canonical order: exposedsitelocs resolved, the sites no rule can use included.

opensites(poly::AbstractPolyform)

The BindingSite of every site of poly a partner can still attach through, in canonical order: opensitelocs resolved.

exposedsitelocs(poly::AbstractPolyform)

The ParticleSiteLoc of every unbound binding site of poly, in canonical order.

Bound sites are consumed by the bonds holding poly together and are never listed. Sites whose color takes part in no rule are listed, even though nothing can attach through them as poly stands; opensitelocs is this list without them.

Addresses rather than the sites themselves, since bindingsite(poly, loc) gets the site from the address but nothing gets the address back from a site. A name ending in sites yields BindingSites and one ending in sitelocs yields addresses, throughout.

These are the sites a cluster species may expose. It exposes the open ones by default, and an inert one becomes usable simply by being named and given a live color.

opensitelocs(poly::AbstractPolyform)

The ParticleSiteLoc of every binding site of poly a partner can still attach through: the unbound ones whose color some rule uses, in canonical order.

See exposedsitelocs, which lists the inert ones too.

rotationgroup(p::Polyform)

Return the rotational symmetry group of p as rotations about the centroid of p's particle positions: those carrying every particle onto a particle of the same species, matching position and orientation.

The counterpart of permutationgroup(::Polyform), which returns the same group as particle permutations.

permutationgroup(p::Polyform)

Return the rotational symmetry group of p as particle permutations: one permutation per rotation about the centroid of p's particle positions that carries every particle onto a particle of the same species, matching position and orientation.

The counterpart of rotationgroup(::Polyform), which returns the same group as rotations, and the assembled analogue of permutationgroup(::ParticleSpecies), which permutes a single particle's sites.

length(permutationgroup(p)) should equal symmetrynumber(p), which reads the same order off the graph encoding. Use it to check an encoding rather than to compute the symmetry number, which nauty gives far more cheaply.

The list holds one entry per rotation, so it may repeat: the action on particles is not faithful. A straight chain of cubes turned about the chain axis leaves every particle where it was and still moves the graph. Call unique on the result for the quotient group.

bonds(p::Polyform)

Return a lazy iterator of bonds in p, each one once, as ParticleSiteLoc pairs.

bondindex(poly::AbstractPolyform, src::Integer, dst::Integer; canonidxs=true)

Return the index into bonded_colors(bindingrules(poly)) for the bond between the graph vertices src and dst, or nothing if they don't form a valid bond type.

canonidxs says which numbering src and dst are in: true, the default, for the canonical one that graphrep(poly) and its edges are in, and false for the stable original one that BindingSite.vertices and Particle.leadingvertex are in.

bondindex(poly::AbstractPolyform, a::ParticleSiteLoc, b::ParticleSiteLoc)

Return the index into bonded_colors(bindingrules(poly)) for a bond between the sites a and b of poly, or nothing if their colors form no valid bond type.

interior_edges(p::AbstractPolyform)

Return a lazy iterator over the internal particle edges of graphrep(p).

exterior_edges(p::AbstractPolyform)

Return a lazy iterator over the external edges of graphrep(p), those joining two particles.

A bond contributes several of these, one per vertex pair contact_pairing makes, so use bonds to iterate bonds.

polyenum([f], rules::BindingRules; maxsize=Inf, maxstrs=Inf, kwargs...)

Iterate over all polyforms allowed by rules using reverse search. Polyforms are generated up to size maxsize, and the enumeration terminates after maxstrs structures have been generated. Use the function f to process generated structures and impose constraints.

f(s) must take a structure s and return one of three signals:

• ACCEPT (or true): enumeration continues as normal.
• REJECT (or false): the offspring of the current structure will not be generated.
• BREAK: the enumeration terminates immediately.

To ensure well-defined behavior, the function f may not accept the offspring of structures that it rejects.

All other keyword arguments are passed to the underlying reversesearch routine.

Returns a NamedTuple (; nstructures, largest_size, status), where status is the RSStatus of the underlying reverse search: Finished if the enumeration ran to completion, and otherwise MaxDepthReached, MaxVerticesReached, or BreakTriggered to indicate why it stopped early.

polygen(rules::BindingRules; kwargs...)

Enumerate all polyforms allowed by rules and return them as a Vector, sorted by number of particles. Keyword arguments are forwarded to polyenum.

countpolyforms(rules::BindingRules; maxsize=Inf, exact_budget=5000, kwargs...)

Estimate the number of polyforms allowed by rules, returning a PolyformCount.

The count is exact whenever the enumeration can fit into exact_budget, and is otherwise estimated by randomly subsampling the reverse-search tree beyond the budget. Only polyforms of at most maxsize particles are counted, and finite maxsize is required for inexact counting.

• maxsize=Inf: only count structures with at most this many particles.
• exact_budget=5000: how many structures to enumerate exactly before switching to estimation.
• ntrials=5: number of independent estimates to average.
• eta=1.2: mean number of surviving offspring per subsampled structure, setting the initial keep probability pkeep = η/branching. Must exceed 1, and is refined automatically.
• pkeep=nothing: set the keep probability directly, disabling eta and the automatic refinement.
• maxsamples=10^6: how many structures a single trial may generate beyond the exact budget.
• rng=Random.default_rng(): generator used for the subsampling.

References:

• Knuth, D. E. Estimating the Efficiency of Backtrack Programs. Math. Comp. 29, 122-136 (1975). doi:10.1090/S0025-5718-1975-0373371-6
• McKay, B. D. Isomorph-Free Exhaustive Generation. J. Algorithms 26, 306-324 (1998). doi:10.1006/jagm.1997.0898

See also polyenum, polygen.

PolyformCount(n::Integer, largest_size, size_truncated)
PolyformCount(trials::AbstractVector, largest_size, size_truncated)

Represent the number of polyforms allowed by a set of binding rules, or an estimate thereof.

• n: the number of allowed structures.
• exact: true if n was obtained by complete enumeration, false if it was estimated.
• uncertainty: the standard error of the estimate.
• largest_size: the size of the largest structure. If not exact, this is a lower bound of the true largest size.
• size_truncated: true if the count covers only structures up to a given cutoff size
• trials: the individual estimates that n averages; empty if exact.

bondtypes(p::AbstractPolyform)

Return the bond type of every bond of p, each one once, indexing bonded_colors(bindingrules(p)).

render(p; hidedecorations=true, kwargs...)

Draw a Polyform or ParticleSpecies into a fresh figure, picking a 2D or 3D axis to match its dimension. Provided by the Makie extension, so it needs a backend loaded.

3D output needs a backend with a depth buffer, GLMakie or WGLMakie. CairoMakie sorts primitives instead of depth-testing them, so 3D polyforms show artifacts where faces meet.

bindingrules=rules draws sites no bond can use as inert, which works for a bare species too.

polyformplot(p; kwargs...)

Makie recipe behind render, drawing a polyform or species into a new axis. Provided by the Makie extension.

polyformplot!(ax, p; kwargs...)

Draw a polyform or species onto an axis you already have, the mutating form of polyformplot. Provided by the Makie extension.

ruleeditor(species::ParticleSpecies; output=:rules)

Open a terminal-based geometric editor for constructing binding rules by placing particles on a lattice. species must be a regular polygon (triangle, square, or hexagon); the lattice is inferred from it.

The editor starts with one "instance" of this species. Press digits 1-9 to add more instances (of the same shape but distinct species colors) and switch between them; e.g. pressing 3 for the first time creates species 3 and makes it active. Any species with at least one placed particle contributes to the returned output.

Controls: arrow keys move the cursor, Enter places a particle (only on empty cells), space erases, r/R rotate (the particle under the cursor if any, else the active rotation), digits 1-9 pick the active species, c clears, q accepts. Bonds are inferred from touching site pairs across all placed particles.

output controls the return value:

• :rules (default): a BindingRules object, ready for polyenum/polygen.
• :bonds: the nx4 integer bonds matrix [species1 site1 species2 site2; ...], suitable for pasting back into code as BindingRules(bonds, species).
• :matrix: the Symmetric{Bool} color-indexed interaction matrix, suitable for pasting back as BindingRules(intmat, species).

If nothing is placed, returns nothing regardless of output.