Cluster Expansion Settings
===========================

.. automodule:: clease.settings
    :members: CEBulk, CECrystal, settings_from_json, ClusterExpansionSettings

.. automodule:: clease.io
    :members: cecrystal_from_cif, read_cif


An Example
----------

In many workflows, the CIF file is used only to define the parent crystal structure
(lattice, positions, and spacegroup), while concentration constraints are defined
explicitly by the user in CLEASE. This is especially useful for partially occupied
or mixed-site systems where occupancy values in the CIF should not directly become
model constraints.

The example below shows a typical flow:
1) read the CIF with ``read_cif(...)`` and inspect metadata,
2) build a manual ``Concentration`` from your chemistry assumptions,
3) construct settings with ``cecrystal_from_cif(...)`` using that concentration.

.. code-block:: python

   from clease.io import read_cif, cecrystal_from_cif
   from clease.settings import Concentration

   cif_path = "my_structure.cif"
   atoms, meta = read_cif(cif_path, infer_spacegroup=True)
   # Build manual concentration model
   symbols = [a.symbol for a in atoms]
   # Define allowed species per current symbol.
   allowed = {
      "Li": ["X", "Li"],
      "Ti": ["Ti", "Sn"],
      "Sn": ["Ti", "Sn"],
      "P": ["P"],
      "O": ["O"],
   }
   basis_elements = [allowed.get(a.symbol, [a.symbol]) for a in atoms]
   # Group indices by identical allowed-species list.
   groups = {}
   for i, be in enumerate(basis_elements):
      groups.setdefault(tuple(be), []).append(i)

   con = Concentration(
      basis_elements=basis_elements,
      grouped_basis=list(groups.values()),
   )
   # Step 3: Build CECrystal from the cif file and stated concentration
   settings = cecrystal_from_cif(
      cif_path=cif_path,
      concentration=con,  # explicit concentration overrides default
      spacegroup_override=meta["spacegroup_number"],  # fallback-safe
      size=[(3, 0, 0), (0, 2, 0), (0, 0, 2)],
      max_cluster_dia=[10, 8, 5],
   )
   ...