Structure.from_file() fails if frac_tolerance argument supplied and file is POSCAR

[lnaglecocco]

Python version

3.12.3

Pymatgen version

2024.11.13

Operating system version

Windows 11

Current behavior

Structure.from_file() takes an argument frac_tolerance. This works fine when loading a CIF. However, when the structure file is a POSCAR I get this error:

Traceback (most recent call last):
  File "C:\Users\lnc\Documents\GitHub\2025-11-20_MD_LSCF_analysis\code\tilts-and-correlations.py", line 859, in <module>
    main(sys.argv[1])
  File "C:\Users\lnc\Documents\GitHub\2025-11-20_MD_LSCF_analysis\code\tilts-and-correlations.py", line 479, in main
    struct = Structure.from_file(cif_path, frac_tolerance=0.0)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\lnc\AppData\Local\anaconda3\envs\materials-analysis\Lib\site-packages\pymatgen\core\structure.py", line 3187, in from_file
    struct = cls.from_str(
             ^^^^^^^^^^^^^
  File "C:\Users\lnc\AppData\Local\anaconda3\envs\materials-analysis\Lib\site-packages\pymatgen\core\structure.py", line 3087, in from_str
    struct = Poscar.from_str(input_string, default_names=None, read_velocities=False, **kwargs).structure
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: Poscar.from_str() got an unexpected keyword argument 'frac_tolerance'

Expected Behavior

It should successfully load the structure with frac_tolerance=0

Minimal example

Structure.from_file("POSCAR")

[lnaglecocco]

Note this is a duplicate of #2924

[shyuep]

Hmm... Why should POSCAR take a frac_tol input? The kwargs is meant for pass through. If it is an accepted input for Cif, it works for CIF. But a Poscar does not take a frac_tol input. Why not just remove that arg when you are calling the method?

[lnaglecocco]

@shyuep Fair point, and thanks for getting back to me. I have a script which I run on both CIF outputs from RMCprofile and the POSCAR outputs of MD simulations on the same material, so it would be nice if the script would just run calmly for both. But I realise I can just fix this at my end, as long as atoms don't snap for POSCARs in pymatgen like they would for CIFs (which I don't think they do). I can just do this in my code:

    if file_path.endswith(".cif"):
        struct = Structure.from_file(file_path, frac_tolerance=0.0)
    else: # frac_tolerance will crash if POSCAR is used
        struct = Structure.from_file(file_path)

If there's no plans to add a frac_tolerance argument for the from_string() method in pymatgen/pymatgen/io/vasp/inputs.py, perhaps an exception should be raised at some earlier step, i.e. if from_file() is called with frac_tolerance and a POSCAR file:
raise Exception("frac_tolerance is not a valid argument for Structure.from_file() if structure file is POSCAR format.")
Otherwise from the user perspective it just seems like an internal bug within pymatgen

[shyuep]

@lnaglecocco I understand the situation. The issue here is that Structure.from_file is a convenience method and in itself does not explicitly support frac_tolerance. This is the method signature.

@classmethod
def from_file(  # type:ignore[override]
    cls,
    filename: PathLike,
    primitive: bool = False,
    sort: bool = False,
    merge_tol: float = 0.0,
    **kwargs,
) -> Structure | Self:

The only reason why frac_tolerance works for CIF is that it is passed using the kwargs. The kwargs passthru by definiiton depends on the actual file format. While we can certainly fix it for POSCARs manually as per your suggestion, we'd have to handle the same thing for all the different formats supported by from_file. E.g., Cssr, json, Vasprun, etc. and all these have their own supported kwargs too that are not supported by other formats.

So for now, I think your workaround is the best solution.