Exclude symmetry-fixed parameters from refinement

Author: AndrewSazonov

docs/docs/tutorials/ed-13.ipynb

@@ -2665,7 +2665,7 @@
  ],
  "metadata": {
   "jupytext": {
-   "cell_metadata_filter": "title,tags,-all",
+   "cell_metadata_filter": "tags,title,-all",
    "main_language": "python",
    "notebook_metadata_filter": "-all"
   }

src/easydiffraction/analysis/analysis.py

@@ -105,9 +105,19 @@ class AnalysisDisplay:
     def __init__(self, analysis: 'Analysis') -> None:
         self._analysis = analysis
 
+    def _flush_structure_categories(self) -> None:
+        """
+        Flush pending category updates so symmetry flags are fresh.
+        """
+        project = self._analysis.project
+        for structure in project.structures:
+            structure._need_categories_update = True
+            structure._update_categories()
+
     def all_params(self) -> None:
         """Print all parameters for structures and experiments."""
         project = self._analysis.project
+        self._flush_structure_categories()
         structures_params = project.structures.parameters
         experiments_params = project.experiments.parameters
 
@@ -139,6 +149,7 @@ def all_params(self) -> None:
     def fittable_params(self) -> None:
         """Print all fittable parameters."""
         project = self._analysis.project
+        self._flush_structure_categories()
         structures_params = project.structures.fittable_parameters
         experiments_params = project.experiments.fittable_parameters
 
@@ -172,6 +183,7 @@ def fittable_params(self) -> None:
     def free_params(self) -> None:
         """Print only currently free (varying) parameters."""
         project = self._analysis.project
+        self._flush_structure_categories()
         structures_params = project.structures.free_parameters
         experiments_params = project.experiments.free_parameters
         free_params = structures_params + experiments_params

src/easydiffraction/core/variable.py

@@ -364,10 +364,12 @@ def free(self, v: bool) -> None:
 
     @property
     def symmetry_fixed(self) -> bool:
-        """Whether this parameter is fixed by crystallographic symmetry."""
+        """
+        Whether this parameter is fixed by crystallographic symmetry.
+        """
         return self._symmetry_fixed
 
-    def _set_symmetry_fixed(self, v: bool) -> None:
+    def _set_symmetry_fixed(self, *, value: bool) -> None:
         """
         Mark or unmark this parameter as fixed by symmetry.
 
@@ -378,11 +380,13 @@ def _set_symmetry_fixed(self, v: bool) -> None:
 
         Parameters
         ----------
-        v : bool
+        value : bool
             New symmetry-fixed state.
         """
         validated = self._symmetry_fixed_spec.validated(
-            v, name=f'{self.unique_name}.symmetry_fixed', current=self._symmetry_fixed
+            value,
+            name=f'{self.unique_name}.symmetry_fixed',
+            current=self._symmetry_fixed,
         )
         self._symmetry_fixed = validated
         if validated:

src/easydiffraction/crystallography/crystallography.py

@@ -118,6 +118,17 @@ def _crystal_system_from_name_hm(name_hm: str) -> str | None:
     return crystal_system
 
 
+_CELL_FIXED_AXES_BY_SYSTEM: dict[str, set[str]] = {
+    'cubic': {'lattice_b', 'lattice_c', 'angle_alpha', 'angle_beta', 'angle_gamma'},
+    'tetragonal': {'lattice_b', 'angle_alpha', 'angle_beta', 'angle_gamma'},
+    'orthorhombic': {'angle_alpha', 'angle_beta', 'angle_gamma'},
+    'hexagonal': {'lattice_b', 'angle_alpha', 'angle_beta', 'angle_gamma'},
+    'trigonal': {'lattice_b', 'angle_alpha', 'angle_beta', 'angle_gamma'},
+    'monoclinic': {'angle_alpha', 'angle_gamma'},
+    'triclinic': set(),
+}
+
+
 def _cell_fixed_axes(crystal_system: str) -> set[str]:
     """
     Return cell keys that are dependent on others for a crystal system.
@@ -136,19 +147,7 @@ def _cell_fixed_axes(crystal_system: str) -> set[str]:
     set[str]
         Subset of cell keys that are fixed by symmetry.
     """
-    if crystal_system == 'cubic':
-        return {'lattice_b', 'lattice_c', 'angle_alpha', 'angle_beta', 'angle_gamma'}
-    if crystal_system == 'tetragonal':
-        return {'lattice_b', 'angle_alpha', 'angle_beta', 'angle_gamma'}
-    if crystal_system == 'orthorhombic':
-        return {'angle_alpha', 'angle_beta', 'angle_gamma'}
-    if crystal_system in {'hexagonal', 'trigonal'}:
-        return {'lattice_b', 'angle_alpha', 'angle_beta', 'angle_gamma'}
-    if crystal_system == 'monoclinic':
-        return {'angle_alpha', 'angle_gamma'}
-    if crystal_system == 'triclinic':
-        return set()
-    return set()
+    return _CELL_FIXED_AXES_BY_SYSTEM.get(crystal_system, set())
 
 
 def cell_symmetry_fixed_flags(name_hm: str) -> dict[str, bool]:
@@ -170,7 +169,7 @@ def cell_symmetry_fixed_flags(name_hm: str) -> dict[str, bool]:
     """
     crystal_system = _crystal_system_from_name_hm(name_hm)
     if crystal_system is None:
-        return {key: False for key in _CELL_KEYS}
+        return dict.fromkeys(_CELL_KEYS, False)
     fixed = _cell_fixed_axes(crystal_system)
     return {key: key in fixed for key in _CELL_KEYS}
 
@@ -207,6 +206,12 @@ def _get_wyckoff_exprs(
         log.error('IT_coordinate_system_code is not set')
         return None
 
+    if (it_number, coord_code) not in SPACE_GROUPS:
+        # Space group is not in the local SPACE_GROUPS table (e.g. P 1,
+        # where cryspy reports no coordinate-system codes). Treat as
+        # "no symmetry constraints to apply".
+        return None
+
     entry = SPACE_GROUPS[it_number, coord_code]
     first_position = entry['Wyckoff_positions'][wyckoff_letter]['coords_xyz'][0]
     components = first_position.strip('()').split(',')
@@ -217,9 +222,9 @@ def _fract_fixed_flags(parsed_exprs: list[Expr]) -> dict[str, bool]:
     """
     Return per-axis flags marking coordinates fixed by site symmetry.
 
-    For each axis (x, y, z), the coordinate is considered fixed when
-    the corresponding symbol does not appear as a free symbol in any of
-    the Wyckoff position expressions.
+    For each axis (x, y, z), the coordinate is considered fixed when the
+    corresponding symbol does not appear as a free symbol in any of the
+    Wyckoff position expressions.
 
     Parameters
     ----------
@@ -327,9 +332,9 @@ def atom_site_symmetry_fixed_flags(
     Returns
     -------
     dict[str, bool]
-        Mapping ``'fract_x' / 'fract_y' / 'fract_z'`` to ``True`` if
-        the axis is fully determined by site symmetry. Returns all
-        ``False`` when the Wyckoff position cannot be resolved.
+        Mapping ``'fract_x' / 'fract_y' / 'fract_z'`` to ``True`` if the
+        axis is fully determined by site symmetry. Returns all ``False``
+        when the Wyckoff position cannot be resolved.
     """
     parsed_exprs = _get_wyckoff_exprs(name_hm, coord_code, wyckoff_letter)
     if parsed_exprs is None:

src/easydiffraction/datablocks/structure/categories/atom_sites/default.py

@@ -558,8 +558,8 @@ def _apply_atomic_coordinates_symmetry_constraints(self) -> None:
         Uses the parent structure's space-group symbol, IT coordinate
         system code and each atom's Wyckoff letter.  Atoms without a
         Wyckoff letter are silently skipped. Coordinates fully
-        determined by site symmetry are flagged as ``symmetry_fixed``
-        so they cannot be marked refinable.
+        determined by site symmetry are flagged as ``symmetry_fixed`` so
+        they cannot be marked refinable.
         """
         structure = self._parent
         space_group_name = structure.space_group.name_h_m.value
@@ -589,16 +589,17 @@ def _apply_atomic_coordinates_symmetry_constraints(self) -> None:
             atom.fract_x.value = dummy_atom['fract_x']
             atom.fract_y.value = dummy_atom['fract_y']
             atom.fract_z.value = dummy_atom['fract_z']
-            atom._fract_x._set_symmetry_fixed(fixed_flags['fract_x'])
-            atom._fract_y._set_symmetry_fixed(fixed_flags['fract_y'])
-            atom._fract_z._set_symmetry_fixed(fixed_flags['fract_z'])
+            atom._fract_x._set_symmetry_fixed(value=fixed_flags['fract_x'])
+            atom._fract_y._set_symmetry_fixed(value=fixed_flags['fract_y'])
+            atom._fract_z._set_symmetry_fixed(value=fixed_flags['fract_z'])
 
     @staticmethod
     def _clear_fract_symmetry_fixed(atom: AtomSite) -> None:
-        """Reset the ``symmetry_fixed`` flag on all fract coordinates."""
-        atom._fract_x._set_symmetry_fixed(False)
-        atom._fract_y._set_symmetry_fixed(False)
-        atom._fract_z._set_symmetry_fixed(False)
+        """
+        Reset the ``symmetry_fixed`` flag on all fract coordinates.
+        """
+        for axis_param in (atom._fract_x, atom._fract_y, atom._fract_z):
+            axis_param._set_symmetry_fixed(value=False)
 
     def _apply_adp_symmetry_constraints(self) -> None:
         """
@@ -619,7 +620,7 @@ def _apply_adp_symmetry_constraints(self) -> None:
         for atom in self._items:
             is_aniso = atom.adp_type.value in aniso_types
             # Isotropic ADP is not refinable for aniso atoms
-            atom._adp_iso._set_symmetry_fixed(is_aniso)
+            atom._adp_iso._set_symmetry_fixed(value=is_aniso)
             if not is_aniso:
                 continue
             wl = atom.wyckoff_letter.value
@@ -653,7 +654,7 @@ def _apply_adp_symmetry_constraints(self) -> None:
             for key, is_free in zip(adp_keys, ref_i, strict=False):
                 param = getattr(aniso_entry, key)
                 param.value = dummy[key]
-                param._set_symmetry_fixed(not is_free)
+                param._set_symmetry_fixed(value=not is_free)
 
     def _sync_iso_from_aniso(self) -> None:
         """

src/easydiffraction/datablocks/structure/categories/cell/default.py

@@ -134,7 +134,7 @@ def _apply_cell_symmetry_constraints(self) -> None:
         }
         for key, param in param_by_key.items():
             param.value = dummy_cell[key]
-            param._set_symmetry_fixed(fixed_flags[key])
+            param._set_symmetry_fixed(value=fixed_flags[key])
 
     def _update(
         self,

tests/functional/test_structure_workflow.py

@@ -137,3 +137,103 @@ def test_multiple_atom_sites(self):
             adp_iso=0.3,
         )
         assert len(s.atom_sites) == 2
+
+
+class TestSymmetryFixedParameters:
+    def test_special_position_fract_cannot_be_freed(self, monkeypatch):
+        from easydiffraction.utils.logging import Logger
+
+        project = _make_project()
+        project.structures.create(name='test')
+        s = project.structures['test']
+        s.space_group.name_h_m = 'P m -3 m'
+        s.atom_sites.create(
+            label='La',
+            type_symbol='La',
+            fract_x=0,
+            fract_y=0,
+            fract_z=0,
+            wyckoff_letter='a',
+            adp_iso=0.5,
+        )
+        # Trigger symmetry-flag computation (normally done by display
+        # / fitting, here we call it explicitly).
+        s._need_categories_update = True
+        s._update_categories()
+
+        atom = s.atom_sites['La']
+        assert atom.fract_x.symmetry_fixed is True
+        assert atom.fract_y.symmetry_fixed is True
+        assert atom.fract_z.symmetry_fixed is True
+
+        monkeypatch.setattr(Logger, '_reaction', Logger.Reaction.WARN, raising=True)
+        for parameter in ('fract_x', 'fract_y', 'fract_z'):
+            getattr(atom, parameter).free = True
+        monkeypatch.setattr(Logger, '_reaction', Logger.Reaction.RAISE, raising=True)
+
+        assert atom.fract_x.free is False
+        assert atom.fract_y.free is False
+        assert atom.fract_z.free is False
+
+    def test_cubic_cell_has_only_a_free(self):
+        project = _make_project()
+        project.structures.create(name='test')
+        s = project.structures['test']
+        s.space_group.name_h_m = 'P m -3 m'
+        s._need_categories_update = True
+        s._update_categories()
+
+        assert s.cell.length_a.symmetry_fixed is False
+        assert s.cell.length_b.symmetry_fixed is True
+        assert s.cell.length_c.symmetry_fixed is True
+        assert s.cell.angle_alpha.symmetry_fixed is True
+        assert s.cell.angle_beta.symmetry_fixed is True
+        assert s.cell.angle_gamma.symmetry_fixed is True
+
+    def test_general_position_remains_refinable(self):
+        project = _make_project()
+        project.structures.create(name='test')
+        s = project.structures['test']
+        # Default space group is P 1 -- general position 'a'
+        s.atom_sites.create(
+            label='La',
+            type_symbol='La',
+            fract_x=0.1,
+            fract_y=0.2,
+            fract_z=0.3,
+            wyckoff_letter='a',
+            adp_iso=0.5,
+        )
+        s._need_categories_update = True
+        s._update_categories()
+
+        atom = s.atom_sites['La']
+        assert atom.fract_x.symmetry_fixed is False
+        atom.fract_x.free = True
+        assert atom.fract_x.free is True
+
+    def test_changing_space_group_updates_flags(self, monkeypatch):
+        from easydiffraction.utils.logging import Logger
+
+        project = _make_project()
+        project.structures.create(name='test')
+        s = project.structures['test']
+
+        # Start in P 1: cell free
+        s._need_categories_update = True
+        s._update_categories()
+        assert s.cell.length_b.symmetry_fixed is False
+        s.cell.length_b.free = True
+        assert s.cell.length_b.free is True
+
+        # Switch to cubic: length_b becomes fixed
+        s.space_group.name_h_m = 'P m -3 m'
+        s._update_categories()
+        assert s.cell.length_b.symmetry_fixed is True
+        assert s.cell.length_b.free is False
+
+        # Setting free=True is now ignored with a warning
+        monkeypatch.setattr(Logger, '_reaction', Logger.Reaction.WARN, raising=True)
+        s.cell.length_b.free = True
+        monkeypatch.setattr(Logger, '_reaction', Logger.Reaction.RAISE, raising=True)
+        assert s.cell.length_b.free is False

tests/unit/easydiffraction/analysis/test_analysis_show_empty.py

@@ -18,6 +18,9 @@ def fittable_parameters(self):
         def free_parameters(self):
             return []
 
+        def __iter__(self):
+            return iter(())
+
     class P:
         structures = Empty()
         experiments = Empty()

tests/unit/easydiffraction/core/test_parameters.py

@@ -101,3 +101,57 @@ def test_parameter_fit_bounds_assign_and_read():
     p.fit_max = 10.0
     assert np.isclose(p.fit_min, -1.0)
     assert np.isclose(p.fit_max, 10.0)
+
+
+def _make_param() -> object:
+    from easydiffraction.core.validation import AttributeSpec
+    from easydiffraction.core.variable import Parameter
+    from easydiffraction.io.cif.handler import CifHandler
+
+    return Parameter(
+        name='p',
+        value_spec=AttributeSpec(default=0.0),
+        cif_handler=CifHandler(names=['_param.p']),
+    )
+
+
+def test_parameter_symmetry_fixed_default_is_false():
+    p = _make_param()
+    assert p.symmetry_fixed is False
+
+
+def test_parameter_set_symmetry_fixed_forces_free_false():
+    p = _make_param()
+    p.free = True
+    assert p.free is True
+    p._set_symmetry_fixed(value=True)
+    assert p.symmetry_fixed is True
+    assert p.free is False
+
+
+def test_parameter_free_true_ignored_when_symmetry_fixed(monkeypatch):
+    from easydiffraction.utils.logging import Logger
+
+    p = _make_param()
+    p._set_symmetry_fixed(value=True)
+    monkeypatch.setattr(Logger, '_reaction', Logger.Reaction.WARN, raising=True)
+    p.free = True
+    assert p.free is False
+    assert p.symmetry_fixed is True
+    monkeypatch.setattr(Logger, '_reaction', Logger.Reaction.RAISE, raising=True)
+
+
+def test_parameter_free_false_allowed_when_symmetry_fixed():
+    p = _make_param()
+    p._set_symmetry_fixed(value=True)
+    p.free = False  # should not warn or raise
+    assert p.free is False
+
+
+def test_parameter_clearing_symmetry_fixed_allows_free_true():
+    p = _make_param()
+    p._set_symmetry_fixed(value=True)
+    p._set_symmetry_fixed(value=False)
+    p.free = True
+    assert p.free is True
+    assert p.symmetry_fixed is False