{"id":8693,"library":"symfc","title":"Symmetry-adapted Force Constants (symfc)","description":"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.","status":"active","version":"1.6.1","language":"en","source_language":"en","source_url":"https://github.com/symfc/symfc","tags":["physics","materials science","phonons","force constants","crystallography","symmetry","HPC","scientific computing"],"install":[{"cmd":"pip install symfc","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Numerical operations and array handling.","package":"numpy"},{"reason":"Scientific computing functionalities, particularly linear algebra and optimization.","package":"scipy"},{"reason":"Crucial for crystal symmetry operations and space group determination.","package":"spglib"}],"imports":[{"note":"The main 'Symfc' class is nested within the 'symfc' submodule, not directly exposed at the top level of the package.","wrong":"from symfc import Symfc","symbol":"Symfc","correct":"from symfc.symfc import Symfc"},{"note":"The 'Phonon' class was moved from 'symfc.calculator' to 'symfc.phonon_calculator' in v1.1.0.","wrong":"from symfc.calculator import Phonon","symbol":"Phonon","correct":"from symfc.phonon_calculator import Phonon"}],"quickstart":{"code":"import numpy as np\nfrom symfc.symfc import Symfc\n\n# In a real scenario, these would come from your simulation or experiment.\n# lattice: 3x3 matrix representing the supercell lattice vectors.\n# positions: Nx3 array of atomic positions in fractional coordinates within the supercell.\n# numbers: N array of atomic numbers for each atom in the supercell.\n# forces: M x (N*3) array of forces for M displacement datasets.\n# displacements: M x (N*3) array of displacements for M displacement datasets.\n\n# --- Dummy Data for demonstration (replace with your actual data) ---\n# Example: a 1-atom supercell (highly simplified, not practical for real phonon calcs)\nnum_atom_supercell = 1\nnum_displacement_datasets = 1\n\nlattice = np.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]])\npositions = np.array([[0.0, 0.0, 0.0]]) # Single atom at origin\nnumbers = np.array([1]) # Hydrogen atom\n\nforces = np.random.rand(num_displacement_datasets, num_atom_supercell * 3)\ndisplacements = np.random.rand(num_displacement_datasets, num_atom_supercell * 3)\ndataset_weights = np.ones(num_displacement_datasets)\n# --- End Dummy Data ---\n\n# Instantiate the Symfc calculator\ntry:\n    calculator = Symfc(\n        forces=forces,\n        displacements=displacements,\n        supercell_lattice=lattice,\n        supercell_positions=positions,\n        supercell_numbers=numbers,\n        # For this quickstart, assume primitive cell is the same as supercell\n        primitive_lattice=lattice,\n        primitive_positions=positions,\n        primitive_numbers=numbers,\n        dataset_weights=dataset_weights,\n        physical_units=True # Set to False if your units are already compatible\n    )\n    print(\"Symfc object instantiated successfully.\")\n\n    # To compute force constants, you would typically call:\n    # force_constants = calculator.run()\n    # print(\"Force constants calculated (shape will vary):\", force_constants.shape)\n\nexcept Exception as e:\n    print(f\"Error instantiating Symfc: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update your import statements: `from symfc.phonon_calculator import Phonon`.","message":"The 'Phonon' class was moved from `symfc.calculator` to `symfc.phonon_calculator` in version 1.1.0.","severity":"breaking","affected_versions":">=1.1.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify `spglib` installation: `pip install spglib`. If problems persist, check `spglib`'s own documentation for installation troubleshooting or environment-specific issues.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"The `Symfc` class is nested within its own submodule. Use `from symfc.symfc import Symfc`.","cause":"Attempting to import the `Symfc` class directly from the top-level `symfc` package.","error":"ImportError: cannot import name 'Symfc' from 'symfc'"},{"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([...])`.","cause":"Passing lists or incorrectly shaped arrays where `symfc` expects specific numpy array types (e.g., for `forces`, `displacements`, `lattice`).","error":"TypeError: 'list' object cannot be interpreted as an integer"},{"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.","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.","error":"spglib.error.SpglibError: spglib error #..."}]}