Skip to main content

ImportError in ASE 3.27: Migration of Filter Classes

  • Updated

As part of the refactoring in ASE 3.27, the filter-related classes have been moved from the traditional constraints module to the filters module. Consequently, the legacy method of importing from ase.constraints no longer works and will trigger an ImportError. If you encounter this error, please update your code to import these classes from the ase.filters module.

Furthermore, it is recommended to migrate to FrechetCellFilter, as ExpCellFilter has an issue with inconsistent gradients for cell variables (it is not consistent with numerical derivatives).

Please note that the filters module, including FrechetCellFilter, has been available since ASE 3.23.

 

Classes implemented in the filters module (the filter-related classes): 

  • Filter
  • StrainFilter
  • UnitCellFilter
  • ExpCellFilter

  • FrechetCellFilter

    *Note: FrechetCellFilter was newly introduced in ASE 3.23 and does not exist in the legacy ase.constraints module.

 

Reference Links: 

 

Example of warnings messages: In ASE 3.23 – 3.26, the following warnings are displayed when importing ExpCellFilter from ase.constraints.

 

/tmp/ipykernel_2550684/1537781631.py:11: FutureWarning: Import ExpCellFilter from ase.filters
  filt = ExpCellFilter(atoms)
/home/jovyan/.py311/lib/python3.11/site-packages/ase/constraints.py:2449: DeprecationWarning: Use FrechetCellFilter for better convergence w.r.t. cell variables.
  super().__init__(*args, **kwargs)

 

As of January 22, 2026, the current version of pfp-api-client v2.0.2 bundles ASE 3.26. Unless there is a specific requirement, it is recommended to maintain the ASE version compatible with your pfp-api-client rather than manually upgrading ASE to 3.27 alone.

 

Error Details

In ASE 3.27, attempting to import a filter from ase.constraints will result in an ImportError.

 

Example of Import Error: When executing ExpCellFilter imported from ase.constraints in ASE 3.27, an error like the following will be displayed.

 

Code Example: To reproduce the error above, run the following in ASE 3.27:

from ase.constraints import ExpCellFilter
from ase.build import bulk

atoms = bulk('Cu', 'fcc', a=3.6)

filt = ExpCellFilter(atoms)

 

 

Solution

Please import the filter-related class from ase.filters. This method also works in ASE 3.23 – 3.26.

 

 

Code Example: ExpCellFilter

from ase.filters import ExpCellFilter
from ase.build import bulk

atoms = bulk('Cu', 'fcc', a=3.6)

filt = ExpCellFilter(atoms)

 

To use FrechetCellFilter, do the following:

Code Example: FrechetCellFilter

from ase.filters import FrechetCellFilter
from ase.build import bulk

atoms = bulk('Cu', 'fcc', a=3.6)

filt = FrechetCellFilter(atoms)

 

 

Related to

Related articles