Symmetry-adapted Force Constants (symfc)

1.6.1 · active · verified Thu Apr 16

symfc is a Python library designed for calculating symmetry-adapted force constants, a critical component for phonon calculations in materials science. It utilizes crystal symmetry to significantly reduce the computational expense of determining these constants. The current version is 1.6.1, with new releases occurring periodically for bug fixes, performance enhancements, and new features.

Common errors

```
ImportError: cannot import name 'Symfc' from 'symfc'
```
cause Attempting to import the `Symfc` class directly from the top-level `symfc` package.

fix The `Symfc` class is nested within its own submodule. Use `from symfc.symfc import Symfc`.
```
TypeError: 'list' object cannot be interpreted as an integer
```
cause Passing lists or incorrectly shaped arrays where `symfc` expects specific numpy array types (e.g., for `forces`, `displacements`, `lattice`).

fix Ensure all array-like inputs are converted to `numpy.ndarray` and have the correct dimensions and data types, typically float. For example, `forces=np.array([...])`.
```
spglib.error.SpglibError: spglib error #...
```
cause This error originates from `spglib`, indicating an issue with the provided crystal structure data (e.g., inconsistent lattice vectors, atomic positions, or numbers) or a problem within `spglib` itself.

fix Double-check your `supercell_lattice`, `supercell_positions`, and `supercell_numbers` inputs for consistency and validity. Consult `spglib` documentation for common crystal structure definition pitfalls.

Warnings

breaking The 'Phonon' class was moved from `symfc.calculator` to `symfc.phonon_calculator` in version 1.1.0.
Fix: Update your import statements: `from symfc.phonon_calculator import Phonon`.
gotcha Input data for crystal structures (lattice, positions, numbers) and force/displacement arrays must be correctly formatted numpy arrays with specific shapes and data types. Incorrect formatting is a common source of errors.
Fix: Refer to the `symfc` documentation and examples on GitHub for precise input data requirements for `supercell_lattice`, `supercell_positions`, `supercell_numbers`, `forces`, and `displacements`.
gotcha The `spglib` library is a core dependency for symmetry operations. Ensure it is correctly installed and accessible in your environment, especially if installing `symfc` in a complex setup.
Fix: Verify `spglib` installation: `pip install spglib`. If problems persist, check `spglib`'s own documentation for installation troubleshooting or environment-specific issues.

Install

pip install symfc Install stable version

Imports

Symfc
wrong:
```
from symfc import Symfc
```
correct:
```
from symfc.symfc import Symfc
```
The main 'Symfc' class is nested within the 'symfc' submodule, not directly exposed at the top level of the package.
Phonon
wrong:
```
from symfc.calculator import Phonon
```
correct:
```
from symfc.phonon_calculator import Phonon
```
The 'Phonon' class was moved from 'symfc.calculator' to 'symfc.phonon_calculator' in v1.1.0.

Quickstart

This quickstart demonstrates how to import the `Symfc` class and instantiate a `Symfc` object. It uses dummy data for crystal structure (lattice, positions, numbers) and simulation results (forces, displacements). In a real application, these inputs would come from ab initio calculations or experimental data. The `run()` method would then be called on the instantiated object to compute the force constants.

import numpy as np
from symfc.symfc import Symfc

# In a real scenario, these would come from your simulation or experiment.
# lattice: 3x3 matrix representing the supercell lattice vectors.
# positions: Nx3 array of atomic positions in fractional coordinates within the supercell.
# numbers: N array of atomic numbers for each atom in the supercell.
# forces: M x (N*3) array of forces for M displacement datasets.
# displacements: M x (N*3) array of displacements for M displacement datasets.

# --- Dummy Data for demonstration (replace with your actual data) ---
# Example: a 1-atom supercell (highly simplified, not practical for real phonon calcs)
num_atom_supercell = 1
num_displacement_datasets = 1

lattice = np.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]])
positions = np.array([[0.0, 0.0, 0.0]]) # Single atom at origin
numbers = np.array([1]) # Hydrogen atom

forces = np.random.rand(num_displacement_datasets, num_atom_supercell * 3)
displacements = np.random.rand(num_displacement_datasets, num_atom_supercell * 3)
dataset_weights = np.ones(num_displacement_datasets)
# --- End Dummy Data ---

# Instantiate the Symfc calculator
try:
    calculator = Symfc(
        forces=forces,
        displacements=displacements,
        supercell_lattice=lattice,
        supercell_positions=positions,
        supercell_numbers=numbers,
        # For this quickstart, assume primitive cell is the same as supercell
        primitive_lattice=lattice,
        primitive_positions=positions,
        primitive_numbers=numbers,
        dataset_weights=dataset_weights,
        physical_units=True # Set to False if your units are already compatible
    )
    print("Symfc object instantiated successfully.")

    # To compute force constants, you would typically call:
    # force_constants = calculator.run()
    # print("Force constants calculated (shape will vary):", force_constants.shape)

except Exception as e:
    print(f"Error instantiating Symfc: {e}")

view raw JSON →