Add get_primitive_cell() method to Structure class

This commit adds a new method to extract the primitive cell from a
supercell or conventional cell using spglib symmetries.

Features:
- get_primitive_cell() method in Structure class
- Uses spglib.standardize_cell() to find primitive cell
- Supports return_itau parameter for atom mapping
- Exposes symprec, angle_tolerance, and no_idealize options
- Returns copy for already-primitive cells
- Preserves masses dictionary

Includes:
- Comprehensive implementation in cellconstructor/Structure.py
- Test suite in tests/TestPrimitiveCell/test_get_primitive_cell.py
- User documentation in UserGuide/gettingstarted.rst
- Sphinx config fixes in UserGuide/conf.py

Author: mesonepigreco

UserGuide/conf.py

@@ -80,7 +80,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -107,7 +107,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -200,7 +200,7 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
 # -- Options for todo extension ----------------------------------------------
 

UserGuide/gettingstarted.rst

@@ -500,7 +500,80 @@ Vice-versa, you can generate an ASE Atoms structure using the function get_ase_a
    :members: get_ase_atoms
 
 
-	     
+Extract the primitive cell
+--------------------------
+
+When working with crystal structures, you often need to find the primitive cell from a conventional cell or supercell.
+CellConstructor provides the ``get_primitive_cell()`` method that uses spglib to identify the smallest repeating unit
+by exploiting the crystal symmetries.
+
+This is particularly useful when:
+
+- You have a conventional cell and want to reduce it to the primitive cell for computational efficiency
+- You need to identify the irreducible atoms in the unit cell
+- You want to standardize the cell representation
+
+Here is an example of how to extract the primitive cell from a conventional FCC cell:
+
+.. code:: python
+
+   import cellconstructor as CC
+   import cellconstructor.Structure
+   import numpy as np
+
+   # Create a conventional FCC cell (4 atoms)
+   fcc_conv = CC.Structure.Structure()
+   fcc_conv.unit_cell = np.array([[4, 0, 0], [0, 4, 0], [0, 0, 4]], dtype=np.float64)
+   fcc_conv.has_unit_cell = True
+   fcc_conv.atoms = ["Al", "Al", "Al", "Al"]
+   fcc_conv.N_atoms = 4
+   fcc_conv.coords = np.array([
+       [0, 0, 0],
+       [0, 2, 2],
+       [2, 0, 2],
+       [2, 2, 0]
+   ], dtype=np.float64)
+   fcc_conv.masses = {"Al": 26.98}
+
+   # Extract the primitive cell
+   fcc_prim = fcc_conv.get_primitive_cell()
+
+   print("Conventional cell atoms:", fcc_conv.N_atoms)
+   print("Primitive cell atoms:", fcc_prim.N_atoms)
+   print("Primitive cell lattice:")
+   print(fcc_prim.unit_cell)
+
+The method returns a new Structure object containing the primitive cell with:
+
+- Reduced number of atoms (1 atom for FCC primitive instead of 4 in conventional)
+- Primitive lattice vectors
+- Atomic positions in Cartesian coordinates
+- Preserved masses dictionary
+
+You can also obtain the mapping between the original atoms and the primitive atoms using the ``return_itau`` parameter:
+
+.. code:: python
+
+   # Get the primitive cell with the itau mapping
+   fcc_prim, itau = fcc_conv.get_primitive_cell(return_itau=True)
+
+   # itau[i] gives the index of the primitive atom that corresponds to original atom i
+   print("itau mapping:", itau)
+   # Output: [0 0 0 0] - all 4 atoms map to the single primitive atom
+
+Additional parameters allow fine control over the primitive cell search:
+
+- ``symprec``: Symmetry precision tolerance (default: 1e-5)
+- ``angle_tolerance``: Tolerance for angles between basis vectors in degrees (default: -1, disabled)
+- ``no_idealize``: If True, disable idealization of basis vectors (default: False)
+
+If the input structure is already a primitive cell, the method returns a copy of the structure.
+
+
+.. autoclass:: Structures.Structures
+   :members: get_primitive_cell
+
+
 Load and save the dynamical matrix
 ----------------------------------
 

cellconstructor/Structure.py

@@ -1499,6 +1499,130 @@ def get_spglib_cell(self):
         cell = (lattice, positions, numbers)
         return cell
 
+    def get_primitive_cell(self, symprec=1e-5, angle_tolerance=-1.0, no_idealize=False, 
+                           return_itau=False):
+        """
+        GET PRIMITIVE CELL
+        ==================
+        
+        This method uses spglib to find the primitive cell from a supercell structure.
+        It exploits the crystal symmetries to identify the smallest repeating unit.
+        
+        If the input structure is already a primitive cell, a copy is returned.
+        
+        Parameters
+        ----------
+        symprec : float, optional
+            Symmetry precision tolerance in Cartesian coordinates. 
+            Default is 1e-5.
+        angle_tolerance : float, optional
+            Tolerance of angle between basis vectors in degrees. 
+            If negative (default), the angle tolerance is disabled.
+        no_idealize : bool, optional
+            If True, disable idealization of basis vectors and atomic positions.
+            This preserves the original Cartesian coordinates. Default is False.
+        return_itau : bool, optional
+            If True, also return the itau array mapping from input atoms to primitive atoms.
+            Similar to the itau in generate_supercell, this indicates which primitive atom
+            each input atom corresponds to. Default is False.
+            
+        Returns
+        -------
+        Structure or tuple
+            The primitive cell structure. If return_itau is True, returns a tuple
+            (primitive_structure, itau) where itau is an ndarray indicating
+            which primitive atom each input atom corresponds to.
+            
+        Raises
+        ------
+        ImportError
+            If spglib is not available.
+        ValueError
+            If the structure has no unit cell or if primitive search fails.
+            
+        Notes
+        -----
+        This method requires spglib to be installed. The optional dependency is
+        handled with the __SPGLIB__ flag from the symmetries module.
+        
+        The primitive cell search may change the orientation of the lattice vectors
+        to match spglib's standard conventions, unless no_idealize=True.
+        
+        The masses dictionary is copied from the original structure to the primitive
+        structure, preserving all atomic masses.
+        """
+        # Check if spglib is available
+        if not SYM.__SPGLIB__:
+            raise ImportError("Error, get_primitive_cell requires spglib to be installed.")
+        
+        # Check if structure has unit cell
+        if not self.has_unit_cell:
+            raise ValueError("Error, the structure must have a valid unit cell to find the primitive cell.")
+        
+        # Get the spglib cell representation
+        cell = self.get_spglib_cell()
+        
+        # Use spglib to find the primitive cell
+        # standardize_cell with to_primitive=True is the modern recommended approach
+        primitive_cell = SYM.spglib.standardize_cell(
+            cell, 
+            to_primitive=True, 
+            no_idealize=no_idealize,
+            symprec=symprec,
+            angle_tolerance=angle_tolerance
+        )
+        
+        if primitive_cell is None:
+            raise ValueError("Error, spglib failed to find the primitive cell. "
+                           "The structure may be too distorted or symprec too strict.")
+        
+        # Unpack the primitive cell data
+        primitive_lattice, primitive_positions, primitive_numbers = primitive_cell
+        
+        # Create a new Structure for the primitive cell
+        primitive_struct = Structure()
+        primitive_struct.has_unit_cell = True
+        primitive_struct.unit_cell = np.array(primitive_lattice, dtype=np.float64)
+        
+        # Convert fractional positions to Cartesian coordinates
+        # primitive_positions are in fractional coordinates of the primitive lattice
+        primitive_struct.coords = np.zeros((len(primitive_positions), 3), dtype=np.float64)
+        for i, pos in enumerate(primitive_positions):
+            # Convert fractional to Cartesian: r_cart = r_frac * lattice_vectors
+            primitive_struct.coords[i, :] = np.dot(pos, primitive_lattice)
+        
+        primitive_struct.N_atoms = len(primitive_numbers)
+        
+        # Map atomic numbers back to symbols
+        # We need to reverse the mapping from get_spglib_cell()
+        # Build the forward mapping first (same logic as get_spglib_cell)
+        forward_mapping = {}
+        for s in self.atoms:
+            forward_mapping.setdefault(s, len(forward_mapping) + 1)
+        
+        # Create reverse mapping: number -> symbol
+        reverse_mapping = {v: k for k, v in forward_mapping.items()}
+        
+        # Assign atomic symbols
+        primitive_struct.atoms = [reverse_mapping[num] for num in primitive_numbers]
+        
+        # Copy the masses dictionary from the original structure
+        primitive_struct.masses = self.masses.copy()
+        
+        # Handle return_itau
+        if return_itau:
+            # Get the symmetry dataset which contains the mapping information
+            dataset = SYM.spglib.get_symmetry_dataset(cell, symprec=symprec, angle_tolerance=angle_tolerance)
+            if dataset is None:
+                raise ValueError("Error, spglib failed to get symmetry dataset for itau mapping.")
+            
+            # mapping_to_primitive gives the index of the primitive atom for each input atom
+            # This is analogous to itau in generate_supercell
+            itau = np.array(dataset.mapping_to_primitive, dtype=np.intc)
+            return primitive_struct, itau
+        
+        return primitive_struct
+
     def get_phonopy_calculation(self, supercell = [1,1,1]):
         """
         Convert the CellConstructor structure to a phonopy object