Canonical Monte Carlo (NVT) on a bimetallic nanoparticle
========================================================

This example uses :class:`CanonicalEnsemble` to sample fixed-composition
configurations of a small Au/Pt cluster at constant temperature. Trial
configurations are generated by ASE's Genetic Algorithm (GA) operators
(``op_list``), relaxed locally, and accepted with the Metropolis rule.

Goal
----

For a 38-atom Au\ :sub:`19`\Pt\ :sub:`19` truncated-octahedral cluster at
:math:`T = 800\,\mathrm{K}`, sample low-energy chemical orderings without
changing the atom count.

Code
----

.. code-block:: python

   from ase.cluster import Octahedron
   from ase.calculators.emt import EMT
   from ase.ga.standardmutations import PermutationMutation
   from ase.ga.utilities import closest_distances_generator
   from ase.ga import OperationSelector
   from ase.optimize import LBFGS

   from mcpy.ensembles.canonical_ensemble import CanonicalEnsemble

   # Build a small Au/Pt cluster (half Au, half Pt).
   atoms = Octahedron('Au', length=4, cutoff=1)
   half = len(atoms) // 2
   atoms.symbols = ['Au'] * half + ['Pt'] * (len(atoms) - half)
   atoms.calc = EMT()

   # GA operator list: a single permutation mutation (swap species).
   blmin = closest_distances_generator(['Au', 'Pt'], ratio_of_covalent_radii=0.7)
   op_list = OperationSelector(
       [1.0],
       [PermutationMutation(n_top=len(atoms), probability=1.0, blmin=blmin)],
   )

   mc = CanonicalEnsemble(
       atoms=atoms,
       calculator=EMT(),
       optimizer=LBFGS,
       fmax=0.1,
       temperature=800.0,
       op_list=op_list,
       random_seed=7,
       outfile='mc_nvt.out',
       traj_file='mc_nvt.xyz',
       outfile_write_interval=10,
       trajectory_write_interval=1,
   )
   mc.run(steps=2_000)

Outputs
-------

- ``mc_nvt.out`` — step log with the running lowest energy.
- ``mc_nvt.xyz`` — every accepted configuration, one frame per acceptance.

Interpretation
--------------

- :class:`CanonicalEnsemble` does **not** insert or delete atoms — the total
  number of Au and Pt is conserved across the run.
- The configurations it writes to disk are *post-relaxation* — energies are
  directly comparable across frames.
- Replace ``PermutationMutation`` with any ASE GA operator (e.g.
  ``RattleMutation``) to sample positional disorder instead of chemical
  ordering.

Next steps
----------

- For variable composition, switch to :doc:`gcmc_simulations`.
- See :doc:`../moves` for the GCMC-side move set.