Open Boundary Suare-Triangle-Shield-Egg Tiling Monte Carlo Simulator

Overview

This repository provides a Monte Carlo simulator for open-boundary square–triangle tilings with shield- and egg-shaped defects. The code implements a vertex model where local updates sample tilings under a configurable defect energy functional. The implementation targets reproducible generation of the simulation data accompanying the square–triangle defect study and is written in Rust for performance and robust memory management.

Key capabilities:

• Generate [D, I] Stampfli tilings either randomly or initialize from stored parquet snapshots
• Run long Markov-chain Monte Carlo (MCMC) trajectories with vertex moves
• Track detailed acceptance and orientation statistics and energy contributions from line tension and defect costs
• Emit tiling geometry and measurement data as Apache Parquet files for efficient downstream analysis in your prefered language

The primary entry point is src/main.rs, which wires command-line parsing to the simulator defined in src/mcmc.rs and the tiling data structures under src.

Repository Layout

• Cargo.toml – crate metadata and dependency lock-in
• src – core simulation engine (tiling representation, move set, RNG, and MCMC driver)
• output – default location for generated data (user-facing simulations typically point elsewhere)

Prerequisites

The project relies on stable Rust and the Apache Arrow ecosystem.

• Rust toolchain: rustc 1.78 or newer (install via rustup)
• Cargo (bundled with rustup)
• C toolchain (clang or gcc) for building native dependencies of the polars crate

Building

Clone the repository and build in release mode for production runs:

git clone https://github.com/alptug/square-triangle-shield-egg-OBMCsim.git
cd square-triangle-shield-egg-OBMCsim
cargo build --release

Release binaries are placed in target/release. Debug builds (cargo build) deliver faster compile cycles but reduced performance.

Command-Line Interface

Run the simulator through cargo or the compiled binary. Append --help to list options:

cargo run --release -- --help

All options are long-form flags. Unless noted, values are required. Defaults match the arguments in src/main.rs.

Flag	Type	Default	Description
--seed	u32	0	RNG seed; draws from host entropy when set to 0
--sweeps	usize	4000000	Number of MCMC sweeps to perform
--annealing-sweeps	usize	0	Optional simulated annealing sweeps before production
--output-interval	usize	1000	Frequency (in sweeps) for logging statistics
--snapshot-interval	usize	4000	Frequency (in sweeps) to write geometry snapshots
--output-dir	String	auto	Directory for parquet output; auto expands to data_D-{D}_I-{I}_gamma-{line_tension}_el-{egg_l}_er-{egg_r}_sh-{shield}
-d	u32	–	Stampfli parameter D; required unless --initialize-from-file is used
-i	u32	–	Stampfli parameter I; required unless --initialize-from-file is used
--line-tension	f64	–	Line tension βγa applied to the boundary length
--egg-l-cost	f64	–	Energy cost for left-egg defects
--egg-r-cost	f64	–	Energy cost for right-egg defects
--shield-cost	f64	–	Energy cost for shield defects
--square-cost	f64	0.0	Optional energy cost per square tile
--triangle-cost	f64	0.0	Optional energy cost per triangle tile
--initialize-from-file	String	–	Path to a parquet vertex snapshot to resume from; bypasses --d and --i

Basic Workflows

1. Fresh simulation from Stampfli seed

   cargo run --release -- \
       -d 2 -i 1 \
       --line-tension 4.0 \
       --egg-l-cost 2.5 --egg-r-cost 2.5 --shield-cost 2.5 \
       --sweeps 1000 --snapshot-interval 100
   

   This generates an automatic output directory reflecting the parameter tuple. The run emits acceptance metrics every output_interval sweeps.

2. Resume from saved configuration

   cargo run --release -- \
       --initialize-from-file vertices_XXXXXXX.parquet \
       --line-tension 3.0 \
       --egg-l-cost 3.0 --egg-r-cost 3.0 --shield-cost 3.0 \
       --sweeps 1000000 --output-dir output_XXXXX/
   

   Provide a directory explicitly when resuming to avoid overwriting reference datasets.

3. Annealed start-up

   cargo run --release -- \
       -d 2 -i 2 \
       --line-tension 5.5 \
       --egg-l-cost 7.0 --egg-r-cost 7.0 --shield-cost 7.0 \
       --annealing-sweeps 50000 --sweeps 1500000
   

   The annealer internally ramps defect penalties and line tension from gentle starting values before production.

Output Artifacts

Each run writes Apache Parquet files to the selected directory.

• metadata.parquet — scalar run metadata (system size, energy parameters, RNG seed, sweep counts).
• measurements.parquet — sweep-resolved statistics appended over time. Columns include MCsweep, tile counts (n_sq*, n_tr*, n_sh*, n_el*, n_er*), boundary length l_bd, and directional edge counts dir1–dir6.
• edges_.parquet — edge list at the chosen snapshot sweeps with columns: source, target (vertex indices), orientation (12-fold orientation index), and type (Internal, Boundary, Hair, Mobile).
• vertices_.parquet — vertex positions in the internal 4D embedding, adjacency table (nb1–nb12, with -1 marking missing neighbors), and vertex classification (kind / kindID).

Files share a zero-padded sweep index matching the total number of requested sweeps. All parquet datasets can be inspected with Polars or Pandas.

Performance Notes

• Set RUST_BACKTRACE=1 when debugging unexpected aborts.
• The binary pins POLARS_MAX_THREADS=1; override before execution if multi-threaded parquet writes are acceptable.

Citation

Please cite the companion paper and this software when publishing results derived from the simulator. A canonical BibTeX entry will be provided in the manuscript; until then, cite the repository as:

@misc{square_triangle_defect_rs,
	author       = {Ulug\"{o}l, Alptu\u{g}},
	title        = {Open Boundary Square-Triangle-Shield-Egg Tiling Monte Carlo Simulator},
	year         = {2026},
	howpublished = {GitHub repository},
	url          = {https://github.com/alptug/square-triangle-shield-egg-OBMCsim}
}

License

MIT