Repository navigation
casm update fail report entries are completely empty #387
Description
When running casm update on a binary system, some configurations fail to map and appear in the fail report with every field null:
{
"atomic_deformation_cost" : null,
"best_score" : null,
"energy" : null,
"has_all_required_properties" : false,
"has_any_required_properties" : false,
"is_new_best" : false,
"lattice_deformation_cost" : null,
"properties_origin" : "",
"score" : null,
"selected" : false,
"to_configname" : ""
}
has_any_required_properties: false suggests CASM isn't finding any required properties at all, and never reaches the geometric mapping stage. But the properties.calc.json files look correct — valid JSON, right fields (energy, atom_coords, atom_type, lattice_vectors, coordinate_mode), consistent atom counts, same structure as configurations that do map successfully.
Question: What does has_any_required_properties: false actually mean internally? What conditions cause the fail report to be completely empty rather than showing actual mapping costs? Is there a way to get more verbose output to diagnose why these specific configurations are being rejected before mapping is attempted?
CASM version: 1.2.0
Activity
bpuchala commentedon Sep 18, 2026
Hi-
It is likely that what happened is the mapping failed and then a fully null report was returned for that configuration. In CASM v1, a complete mapping failure typically means a structure that should not be included in your fitting data.
The most likely cause of a mapping failure like that is a strong relaxation to a different parent crystal such that there are >1 equivalently bad best mappings. Other causes of mapping failure include an atom type not allowed in the project (not likely for CASM update) or an extremely poor mapping score. More than 1 equally scored best mappings is the most common failure.
Often my suggestion is to just manually inspect the structure you are trying to import to confirm it is one that should not excluded from your fit. Of course if there are many failures that can be time consuming.
We have improved access to the mapping methods in CASM v2's libcasm-mapping. The method libcasm.mapping.methods.map_structures can be used directly to find mappings and more flexibly determine what the failure cause is.
I asked Claude to write a script to use CASM v2 to diagnose why CASM v1 failed to map a calculated structure. I have attached it in case it is useful.
diagnose_mapping.py
chen3785 commentedon Sep 21, 2026
Thank you for the response and the diagnostic script, very helpful!
I ran diagnose_mapping.py on all the failing configurations and they all come back as TIE. The deformations are small and in most cases the starting configuration is among the tied candidates. Some are "TIE (same config)" where the correct configuration is unambiguous but multiple lattice mappings tie, and some are "TIE (different configs)" where the relaxed structure maps equally well onto two different configurations.
What would you suggest for handling each of these cases practically in CASM v1.2? For example, would using a stricter cost_tol help?
bpuchala commentedon Sep 22, 2026
It really depends on what the right effective Hamiltonian is for your system. If an initial ideal configuration relaxes to two or more distinct states (local minima) with different strains or displacements, then that ideal configuration is not a good representative for the true state. If you used that prim in Monte Carlo, then the equilibrium state occupancies would not be correct. There are some things to consider:
casm update -c failed.json -i '{"force": true, "mapping": {"fix_lattice": true}}'to only map make to the lattice of the starting supercell, 3) try manually copy the mapping you want into the properties JSON file, or 4) use CASM v2 which is less restrictive, for better or worse.chen3785 commentedon Oct 12, 2026
Thanks for the detailed response.
I figured out that the root cause was a symmetry issue, not heavy deformation. My original prim was defined as rhombohedral but very close to cubic. In some cases, DFT would relax the structure all the way to cubic, which caused the mapping to fail.
I switched to a cubic prim and let DFT relax to rhombohedral naturally if the energy landscape allows for it. Since making that change, the mapping issues have completely gone away.
Thanks again for the help, much appreciated!