I/O (flake.io)

File I/O for rigid-cluster simulations.

HDF5 format (via h5py) is used for all numerical results. Each dataset name in the file matches the dict key returned by the map functions. Metadata (scalar parameters, substrate/cluster settings) is stored as HDF5 attributes; numpy arrays and nested structures in params are serialised as JSON strings to avoid HDF5 group complexity.

YAML format (via PyYAML) is used for human-editable parameter files.

Neither h5py nor yaml is imported at module level – both are guarded so the module can be imported even if the optional dependency is absent; only the relevant function call raises ImportError.

flake.io.load_map(filename)

Load HDF5 map file.

Returns:

(result_dict, params_dict) – both plain Python dicts. result_dict values are numpy arrays; params_dict values are Python scalars, strings, or dicts (JSON-decoded where applicable).

flake.io.load_params(filename)

Load a YAML (or JSON) parameter file.

Args:

filename: str – path to .yaml or .json file.

Returns:

dict

flake.io.load_trajectory(filename)

Load HDF5 trajectory file.

Returns:

(traj_dict, params_dict)

flake.io.make_sin_params(n_symmetry, spacing)

Build substrate parameter dict for an n-fold sinusoidal potential.

Equivalent to running create_PW_sub.py from the old snips/ directory.

Args:

n_symmetry: int – fold symmetry (2, 3, 4, 5, or 6). spacing: float – lattice spacing (same units as cluster positions).

Returns:

dict with keys ‘well_shape’ and ‘ks’ ready to merge into a full params dict.

Raises:

ValueError: if n_symmetry is not in {2, 3, 4, 5, 6}.

flake.io.save_map(result_dict, filename, params=None)

Save a map result dict to HDF5.

Args:

result_dict: dict of numpy arrays (output of translational_map etc.). filename: str – output path (should end in .h5 or .hdf5). params: optional dict of scalar/string/array metadata.

flake.io.save_params(params, filename)

Save a parameter dict to YAML.

Args:

params: dict – parameters to write. filename: str – output path.

flake.io.save_trajectory(traj_dict, filename, params=None)

Save an MD trajectory dict to HDF5.

Expected keys: ‘t’, ‘energy’, ‘pos_cm’, ‘vel_cm’, ‘theta’, ‘omega’, ‘force’, ‘torque’. Any subset is accepted.

Args:

traj_dict: dict of numpy arrays. filename: str – output path. params: optional dict of metadata.

Plotting (flake.plot)

Plotting utilities for FLAKE.

Public API

plot_UC – draw the real-space unit cell on a matplotlib axis. get_brillouin_zone_2d – compute BZ vertices via Voronoi decomposition. plot_BZ2d – add BZ polygon patch to a matplotlib axis. plt_cosmetic – set axis labels, zero lines, and equal aspect. plot_lattice_vectors – draw primitive lattice vectors as arrows.

flake.plot.get_brillouin_zone_2d(cell)

Compute the vertices of the 2D Brillouin Zone (Wigner-Seitz cell of reciprocal lattice).

Uses Voronoi decomposition of the reciprocal lattice.

Args:

cell: (2, 2) array-like – rows are the two reciprocal lattice vectors.

Returns:

(M, 2) float64 ndarray – vertices of the BZ polygon.

flake.plot.plot_BZ2d(ax, ws_verts, params=None)

Add the Brillouin Zone polygon to a matplotlib axis.

Args:

ax: matplotlib Axes. ws_verts: (M, 2) array-like – BZ vertices (e.g. from get_brillouin_zone_2d). params: dict – Polygon kwargs (ls, color, lw, fill, …).

Returns:

(ax, ws_cell) – axis and the Polygon patch.

flake.plot.plot_UC(ax, u, params=None)

Draw the real-space unit cell spanned by u[0], u[1] on ax.

Args:

ax: matplotlib Axes. u: (2, 2) array-like – two primitive lattice vectors. params: dict – line style kwargs forwarded to ax.plot.

Returns:

ax

flake.plot.plot_lattice_vectors(ax, S, colors=('tab:red', 'tab:orange'), labels=('b1', 'b2'))

Draw the two primitive lattice vectors as arrows from the origin.

Args:

ax: matplotlib Axes. S: (2, 2) array-like – rows are the two lattice vectors. colors: tuple of str – arrow colours. labels: tuple of str – legend labels.

Returns:

ax

flake.plot.plt_cosmetic(ax, xlabel='x', ylabel='y')

Add zero lines, axis labels and equal aspect to ax.

Args:

ax: matplotlib Axes. xlabel: str – x-axis label. ylabel: str – y-axis label.