Clean up the code

examples/PbSnTe.cif

@@ -227,6 +227,6 @@ _atom_site_fract_x
 _atom_site_fract_y
 _atom_site_fract_z
 _atom_site_occupancy
-Pb1 Pb2+ 4 a 0.0 0.0 0.0 0.75000
-Sn1 Sn2+ 4 a 0.0 0.0 0.0 0.25000
-Te1 Te2- 4 b 0.5 0.5 0.5 1.00000
+Pb1 Pb 4 a 0.0 0.0 0.0 0.75000
+Sn1 Sn 4 a 0.0 0.0 0.0 0.25000
+Te1 Te 4 b 0.5 0.5 0.5 1.00000

examples/README.md

@@ -3,47 +3,47 @@
 What each script does, summarized per example. All required CIF inputs are bundled in this directory.
 
 ## Example 1: Basic enumeration and CIF output
-- File: [examples/example1.py](examples/example1.py)
+- File: [example1.py](example1.py)
 - What it does: Load `SmFe7Ti.cif`, use `Substitutor` to generate all symmetry-inequivalent structures, and write CIFs with their multiplicity (weight).
 - Key point: Uses `Substitutor.quantities(("cifwriter", "weight"))` and saves to `output/` as `cif_i{index}w{weight}.cif`.
 
 ## Example 2: Comparison with enumlib
-- File: [examples/example2.py](examples/example2.py)
+- File: [example2.py](example2.py)
 - What it does: Expand `PbSnTe.cif` to a 2×2×2 supercell and compare enumeration results between Pymatgen's `EnumlibAdaptor` and SHRY.
 - Comparison modes:
   - SHRY default (group equivalent sites).
   - SHRY with `groupby=lambda x: x.species` (group by species, similar to enumlib behavior).
 - Output: Prints the number of structures from each approach to stdout.
 
 ## Example 3: LabeledStructure and label-based substitutions
-- File: [examples/example3.py](examples/example3.py)
+- File: [example3.py](example3.py)
 - What it does: Load `SmFe12.cif` as a `LabeledStructure`, replace labels `Fe1`→`Fe3Ti`, `Fe2`→`Fe7Ti`, `Fe3`→`Ti`, then expand to a non-diagonal supercell `((2,0,1),(0,1,0),(1,0,1))`. Generates all structures, writes CIFs and weights to `output/`, and prints configuration letters (e.g., `aba...`).
 - Key point: Keeps `_atom_site_label`, so substitutions remain label-consistent even after supercell expansion.
 
 ## Example 4a: Caching pattern generation and saving it
-- File: [examples/example4a.py](examples/example4a.py)
+- File: [example4a.py](example4a.py)
 - What it does: Load `SmFe12.cif` as a `LabeledStructure`, replace `Fe1`→`Fe7Ti`, run `Substitutor(cache=True)`, write CIFs, and pickle the internal `pattern_makers` to `pg.pkl`.
 - Benefit: Reuse the cached pattern makers to skip expensive recomputation for symmetry-equivalent systems later.
 
 ## Example 4b: Reusing cache and applying to different compositions
-- File: [examples/example4b.py](examples/example4b.py)
+- File: [example4b.py](example4b.py)
 - What it does: Load `pg.pkl` from Example 4a. Starting from `SmFe12.cif`, evaluate two substitution cases (`Fe`→`Fe3Ti` and `Fe`→`FeTi3`) in sequence. Attach the loaded `pattern_makers` to a `Substitutor`, generate CIFs for `run1` and `run2`, then overwrite `pg.pkl` with the updated cache.
 - Key point: When symmetry is the same, you can rapidly iterate different substitution patterns using the cached pattern makers.
 
 ## Example 5: Generating ASE Atoms
-- File: [examples/example5.py](examples/example5.py)
+- File: [example5.py](example5.py)
 - What it does: Expand `PbSnTe.cif` to 2×2×2, enumerate all structures with `Substitutor`, and obtain them as ASE `Atoms` objects.
 - Output: Prints the number of structures to stdout and shows one sample `Atoms` instance; useful as a bridge to downstream ASE workflows.
 
 ## Example 6: Ranking by Ewald energy
-- File: [examples/example6.py](examples/example6.py)
+- File: [example6.py](example6.py)
 - What it does: Enumerates substitutions, guesses oxidation states, computes Ewald energies, and writes the 100 lowest-energy structures to output_ewald/.
 - Note: If oxidation states cannot be guessed, Ewald energies may be zero or skipped.
 
 ## Example 7: Highest symmetry structures (lowest weight)
-- File: [examples/example7.py](examples/example7.py)
+- File: [example7.py](example7.py)
 - What it does: Enumerates substitutions and writes the top-N structures with the smallest weight (highest symmetry) to output_symm_top/. Optionally writes all structures sorted by weight.
 
 ## Example 8: Merge multiple Wyckoff labels for shared concentration
-- File: [examples/example8.py](examples/example8.py)
+- File: [example8.py](example8.py)
 - What it does: Loads `SmFe12.cif`, relabels multiple Wyckoff labels (e.g., `Fe1` and `Fe2`) into a shared label (`Target`), then applies a single disordered composition (e.g., `Fe0.5Ti0.5`) across that pooled site set. This enables specifying a global substitution concentration across multiple Wyckoff positions.

examples/SmFe12.cif

@@ -8,7 +8,6 @@
 
 data_SmFe12
 
-loop_
 _chemical_formula_sum            'Fe12 Sm'
 _space_group_IT_number           139
 _symmetry_space_group_name_Hall  '-I 4 2'

examples/SmFe7Ti.cif

@@ -7,9 +7,7 @@ data_SmFe12
 # http://www.crystallography.net/
 #
 
-
-loop_
-_chemical_formula_sum            'Fe12 Sm'
+_chemical_formula_sum            'Fe10.5 Sm Ti1.5'
 _space_group_IT_number           139
 _symmetry_space_group_name_Hall  '-I 4 2'
 _symmetry_space_group_name_H-M   'I 4/m m m'
@@ -21,8 +19,8 @@ _cell_length_a                   8.59
 _cell_length_b                   8.59
 _cell_length_c                   4.804
 _cell_volume                     354.478
-_cod_data_source_block           'Fe12 Sm1'
-_cod_original_formula_sum        'Fe12 Sm1'
+_cod_data_source_block           'Fe10.5 Sm1 Ti1.5'
+_cod_original_formula_sum        'Fe10.5 Sm1 Ti1.5'
 loop_
 _symmetry_equiv_pos_as_xyz
 x,y,z

examples/example6.py

@@ -19,7 +19,7 @@
 helper = ScriptHelper(
     structure_file="PbSnTe.cif",  # Replace with your CIF if desired
     from_species=("Sn",),
-    to_species=("Sn0.5Sb0.5",),
+    to_species=("Sn0.5Se0.5",),
     scaling_matrix=(2, 2, 1),  # enlarge to break more symmetry and get multiple patterns
 )
 
@@ -29,7 +29,16 @@
 
 for i, structure in enumerate(helper.substitutor.structure_writers()):
     try:
-        structure.add_oxidation_state_by_guess()
+        # Ensure oxidation states are set explicitly for this system.
+        structure.remove_oxidation_states()
+        structure.add_oxidation_state_by_element(
+            {
+                "Pb": +2,
+                "Sn": +2,
+                "Se": +4,
+                "Te": -2,
+            }
+        )
         energy = EwaldSummation(structure).total_energy
     except Exception as exc:  # noqa: BLE001 - narrow for clarity in real workflows
         print(f"Skipping structure {i}: {exc}")