Static maps (flake.maps)

Static energy maps for rigid-cluster simulations.

Three maps are provided:

• translational_map — \(E(x_\mathrm{cm},\, y_\mathrm{cm})\) at fixed \(\theta\)

• rotational_map — \(E(\theta)\) at fixed CM position

• rototrasl_map — \(E(\theta,\, x_\mathrm{cm},\, y_\mathrm{cm})\) full 3-D scan

All maps return plain dicts of numpy arrays. No file I/O, no logging.

Grid coordinate convention

For Bravais-lattice substrates (Gaussian, tanh), fractional coordinates \((\xi_1, \xi_2) \in [0,1)^2\) are converted to real-space CM positions via:

\[\begin{split}\mathbf{r}_\mathrm{cm} = U^{-1} \begin{pmatrix} \xi_1 \\ \xi_2 \end{pmatrix}\end{split}\]

where \(U^{-1}\) is the matrix from calc_matrices_bvect (columns are the primitive vectors \(\mathbf{b}_1, \mathbf{b}_2\)).

For sinusoidal substrates (no unique unit cell) and quasicrystals (no unit cell at all), pass a pre-built Cartesian grid directly via pos_cm_grid and set u_inv=None.

Parallelism

Set n_jobs > 1 to parallelise over grid points with joblib (loky backend). n_jobs = -1 uses all available cores. For small grids n_jobs = 1 is faster due to process-spawn overhead.

flake.maps.rotational_map(pos, calc_en_f, en_params, theta_deg, pos_cm=(0.0, 0.0), n_jobs=1)

Energy as a function of cluster orientation at fixed CM position.

Args:

pos: (N, 2) ndarray – cluster positions at theta=0. calc_en_f: callable – total energy function. en_params: list – extra arguments for calc_en_f. theta_deg: (n_theta,) array – angles in degrees. pos_cm: (2,) array-like – fixed CM position (default origin). n_jobs: int – parallel workers.

Returns:

dict with keys:

‘theta’ : (n_theta,) – angles in degrees (copy of input). ‘energy’ : (n_theta,) ‘force’ : (n_theta, 2) ‘torque’ : (n_theta,)

flake.maps.rototrasl_map(pos, calc_en_f, en_params, u_inv, theta_deg, n_x, n_y, frac_x=(0.0, 1.0), frac_y=(0.0, 1.0), pos_cm_grid=None, n_jobs=1)

Full energy landscape over (theta, x, y).

For each angle, scans the same translational grid. The parallelism target is the flattened (theta, grid) index.

Args:

pos: (N, 2) ndarray – cluster positions at theta=0. calc_en_f: callable – total energy function. en_params: list – extra arguments for calc_en_f. u_inv: (2, 2) ndarray or None – metric matrix; ignored when

pos_cm_grid is supplied.

theta_deg: (n_theta,) array – angles in degrees. n_x: int – grid points along x (or a1). n_y: int – grid points along y (or a2). frac_x: (float, float) – fractional range along a1;

ignored when pos_cm_grid is supplied.

frac_y: (float, float) – fractional range along a2;

ignored when pos_cm_grid is supplied.

pos_cm_grid: (M, 2) ndarray or None – explicit Cartesian CM positions.

Required for sin substrates and quasicrystals (no unit cell). When given, u_inv/frac_x/frac_y are ignored.

n_jobs: int – parallel workers.

Returns:

dict with keys:

‘theta’ : (n_theta,) ‘pos_cm’ : (n_theta, M, 2) ‘energy’ : (n_theta, M) ‘force’ : (n_theta, M, 2) ‘torque’ : (n_theta, M)

Raises:

ValueError: if both u_inv and pos_cm_grid are None.

flake.maps.translational_map(pos, calc_en_f, en_params, u_inv, n_x, n_y, frac_x=(0.0, 1.0), frac_y=(0.0, 1.0), pos_cm_grid=None, n_jobs=1)

Energy landscape as a function of CM position at fixed orientation.

The cluster orientation is taken as-is from pos (caller rotates first if a non-zero theta is desired).

Args:

pos: (N, 2) ndarray – cluster positions in cluster frame. calc_en_f: callable – total energy function from substrate_from_params. en_params: list – extra arguments for calc_en_f. u_inv: (2, 2) ndarray or None

– metric matrix used to map fractional

coordinates to Cartesian. Ignored (may be None) when pos_cm_grid is supplied.

n_x: int – grid points along first fractional axis;

ignored when pos_cm_grid is supplied.

n_y: int – grid points along second fractional axis;

ignored when pos_cm_grid is supplied.

frac_x: (float, float) – fractional range along a1 (default 0 to 1);

ignored when pos_cm_grid is supplied.

frac_y: (float, float) – fractional range along a2 (default 0 to 1);

ignored when pos_cm_grid is supplied.

pos_cm_grid: (M, 2) ndarray or None

– explicit CM positions in real space.

When not None, bypasses all grid construction from u_inv/n_x/n_y/frac_*. Recommended for sinusoidal substrates (no unique unit cell) and for quasicrystal symmetries (no unit cell at all).

n_jobs: int – joblib parallel workers (1 = serial).

Returns:

dict with keys:

‘pos_cm’ : (M, 2) – CM positions in real space. ‘energy’ : (M,) ‘force’ : (M, 2) ‘torque’ : (M,)