Roly.jl

Roly.jl (Reverse-Search Polyform Enumerator) is a Julia package for the enumeration of arbitrary polyforms via reverse search. It makes it possible to exhaustively enumerate structures composed out of a set of arbitrarily shaped building blocks in 2D or 3D and provides an interface to define your own building block geometries and binding rules. Roly.jl is under active development, and breaking changes can occur at any time. Because of its depencencies, Roly.jl currently does not work on Windows.

Installation

To install Roly.jl and directly from your Julia REPL, first press ] to enter Pkg mode, and then run

pkg> add https://github.com/mxhbl/Roly.jl

Basic Usage

Structure enumeration in Roly.jl starts from an AssemblySystem, which is a list of building block geometries together with an interaction matrix that specificies which binding sites are allowed to bind to each other. The allowed structures can then be enumerated with the function polyenum, or generated and stored with polygen.

Assembly System Definition

To illustrate the basic process, let's construct an assembly system consisting of four species of triangular building blocks. You can define the binding rules via a list of bonds, where every bond is specified in the form [species_i site_i species_j site_j]. For example, [1 3 2 3] indicates that site 3 of species 1 is allowed to bind to site 3 of species 2. Roly already comes with definitions for simple polygonal and polyhedral building block geometries, allowing us to specify triangular building blocks via a UnitTriangleGeometry. The AssemblySystem constructor takes either a list of geometries or a single geometry if all building blocks are identically shaped.

using Roly

bonds = [1 3 2 3;
         2 2 3 2;
         2 1 4 1;
         3 1 4 1]
asys = AssemblySystem(bonds, UnitTriangleGeometry)

Enumeration of Structures

Once you have defined an assembly system, you can use polyenum to enumerate all possible structures:

n_strs, largest_strsize = polyenum(asys; maxsize=20, maxstrs=100_000)

The simple system we have chosen here only allows 16 different structures to form. In general however, the number of structures might be unbounded and it is advisable to always impose either a maximal structure size (maxsize), or maximal number of structures (maxstrs) to be enumerated. In addition, polyenum allows the user to pass a function for processing and selectively rejecting structures.

Generation of Structures

If you want to store all possible structures in memory for further processing, it is often more convenient to use polygen, which simply returns a list of structures:

strs = polygen(asys; maxsize=20, maxstrs=100_000)

Incorporating constraints

It is often desirable to impose additional constraints that the generated structures should satisfy. For example, say we only want to generate structures with at most one particle of species 4:

constraint(s) = composition(s, asys)[4] <= 1
filtered_strs = polygen(constraint, asys) # polyenum works similarly

Warning: To ensure well-defined behavior, if a structure s violates the constraint, all larger structures s' that can be generated by adding particles to s must also violate the constraint.

Visualization

To visualize 2D structures, use RolyVis.jl:

using RolyVis
draw_polyforms(strs, asys, "filename.pdf//png")

Citation

If you use Roly.jl in your work, please cite our paper below:

@article{roly2025, 
         year = {2025}, 
         title = {{Accessing Semiaddressable Self-Assembly with Efficient Structure Enumeration}}, 
         author = {Hübl, Maximilian C. and Goodrich, Carl P.}, 
         journal = {Physical Review Letters}, 
         issn = {0031-9007}, 
         doi = {10.1103/physrevlett.134.058204}, 
         pages = {058204}, 
         number = {5}, 
         volume = {134}, 
         keywords = {}
}