Adopting new policy for STRICT_MODE

[ppravatto]

Proposal: Simplification and Strengthening of STRICT_MODE in SPyCCI

Currently, SPyCCI provides two policies, selectable through the spycci.config.STRICT_MODE flag, for handling System properties originating from calculations performed at different levels of theory.

• With STRICT_MODE=True, the library automatically clears all properties affected by a change in the level of theory, according to the following rules:
  • A change in the electronic level of theory clears electronic energies, free energy, condensed charges, spin populations, Fukui functions, and pKa.
  • A change in the vibronic level of theory clears vibronic energy, free energy, pKa, and all types of vibrational data.
• With STRICT_MODE=False, the library allows data from different levels of theory to coexist without any consistency checks and marks the affected level of theory as undefined.

In both modes, any change in geometry clears all properties.

---

I find the STRICT_MODE=False mode of operation both dangerous and not particularly useful. I propose removing it from the library altogether. Storing data under an undefined level of theory is especially risky now that users can save a System as a .json file and reload it later for further processing.

Proposed Changes

1. Remove support for STRICT_MODE=False, keeping only the current behavior of STRICT_MODE=True.
2. Introduce new policies for stricter consistency checks:
   • STRICT: requires equality between the electronic and vibronic levels of theory.
   • VERY_STRICT: requires equality across geometry, electronic, and vibronic levels of theory.

---

If, in the future, we want to support the storage of electronic and vibrational data from multiple levels of theory, I suggest adopting a dictionary-based structure where individually labelled Property objects associated with different levels of theory can co-exist without ambiguity. This would ensure that all stored data remains clearly identifiable and unambiguous.

@lbabetto and @AresValley I would love to hear your thoughts on this.

[AresValley]

Yes, I fully agree with the proposed changes. I can see a practical use case for STRICT_MODE=True, where consistency across levels of theory is maintained automatically. However, the STRICT_MODE=False behavior, where different properties can originate from different, undefined levels of theory, seems both risky and hard to justify, to be honest.

Allowing properties to coexist without a clear specific level of theory introduces ambiguity, which is particularly problematic now that users can export and later reload System objects via JSON. This could easily lead to errors in workflows if a user is not particularly careful.

Additionally, maintaining support for STRICT_MODE=False will increase the load for both users and developers, who must account for edge cases involving partial or undefined metadata (and again, in my opinion, without real cases (at least from my side) where this behavior is really a wanted one)

[lbabetto]

I'm actually an advocate of a MIXED_MODE, where different levels of theory are combined to compute properties. I agree it's a possibly dangerous route in which the user must be fully aware of what they are doing - hence the default is STRICT_MODE=True - but in some situations I think it makes perfect sense. For example, composite methods mixing Hybrid DFT frequencies with CCSD electronic energies is not something unusual (https://pmc.ncbi.nlm.nih.gov/articles/PMC9739849/ and https://pmc.ncbi.nlm.nih.gov/articles/PMC10413851/) and in some cases is straight up necessary due to computational constraints. Even more ubiquitous are situations in which the geometry is calculated at a lower level of theory, and a higher-level single point calculation is performed on top. This is also technically non-compliant with the STRICT_MODE as far as I understand.

If we're okay with things like ONIOM and QM/MM I think we should also be okay with this, obviously warning the user (possibly, very loudly) that they are not performing "standard" operations, but I would not rule out the possibility altogether.

As for the burden on devs, I agree we should not be the ones making sure nothing breaks, as this is akin to running the software in an "unintended mode", where all repercussions fall solely on the end user (= carry on at your own risk). Routines and functions should be developed within the strict mode constraints.

[ppravatto]

Yes @lbabetto, I completely agree with you on the usefulness of a mixed approach, and I’m also in favor of keeping that possibility available to the user.

That said, I think there is a subtle but important distinction between the name STRICT_MODE and its actual behavior in the current implementation.

In fact, with STRICT_MODE=True, users can already perform calculations involving up to three distinct levels of theory: one for geometry, one for vibrational analysis, and one for electronic structure. This is exactly the kind of setup you described (e.g., DFT for vibrations and CCSD for energies), and it’s also the default behavior in SPyCCI today.

The real difference between STRICT_MODE=True and STRICT_MODE=False is how consistency is enforced within the same category of properties/level of theory. That is:

• With STRICT_MODE=True, if two calculations for (say) vibrational properties are performed at different vibronic levels of theory, SPyCCI will refuse to mix them under a single System object. Instead, it clears the corresponding properties if there's a conflict, maintaining a well-defined level_of_theory_vibronic.

• With STRICT_MODE=False, this safeguard is removed, and conflicting data from different levels of theory may silently coexist, with the level marked as undefined.

So in short: the current strict mode does allow mixed levels — but only when it’s explicit and non-conflicting across categories. This provides flexibility without losing traceability, which I believe is a good compromise between usability and safety.

To clarify what I mean, let me use a deliberately absurd example:

from spycci.systems import System
from spycci.engines.xtb import XtbInput
from spycci.engines.orca import OrcaInput

mol = System("water.xyz", 0, 1)

xtb = XtbInput()
orca = OrcaInput(method="PBE", basis_set="def2-SVP")

orca.freq(mol, ncores=4, inplace=True)

print("Before")
print("----------------------------------------------------------")
print(mol.properties.level_of_theory_electronic)
print(mol.properties.level_of_theory_vibronic)
print(mol.properties.vibronic_energy)
if mol.properties.vibrational_data:
    print(mol.properties.vibrational_data.frequencies[-1])
else:
    print("None")

print()

# Compute a new vibronic property
newmol = xtb.freq(mol, ncores=4)
new_vibronic = newmol.properties.vibronic_energy
mol.properties.set_vibronic_energy(new_vibronic, xtb)

print()
print("After")
print("----------------------------------------------------------")
print(mol.properties.level_of_theory_electronic)
print(mol.properties.level_of_theory_vibronic)
print(mol.properties.vibronic_energy)
if mol.properties.vibrational_data:
    print(mol.properties.vibrational_data.frequencies[-1])
else:
    print("None")

Running with STRICT_MODE=True the output is:

Before
----------------------------------------------------------
OrcaInput || method: PBE | basis: def2-SVP | solvent: None
OrcaInput || method: PBE | basis: def2-SVP | solvent: None
0.00327779
3868.53

[... WARNINGS ...]

After
----------------------------------------------------------
OrcaInput || method: PBE | basis: def2-SVP | solvent: None
XtbInput || method: gfn2 | solvent: None
0.001986858689
None

Running with STRICT_MODE=False the output is:

Before
----------------------------------------------------------
OrcaInput || method: PBE | basis: def2-SVP | solvent: None
OrcaInput || method: PBE | basis: def2-SVP | solvent: None
0.00327779
3868.53

[... WARNINGS ...]

After
----------------------------------------------------------
OrcaInput || method: PBE | basis: def2-SVP | solvent: None
Undefined
0.001986858689
3868.53

As you can see in both cases different levels of theory are used for vibronic and electronic part. In the second case however the vibrational properties computed by orca are kept with those computed by xtb with an Undefined level of theory. I find this behavior not very useful and kind of dangerous.

[ppravatto]

As a further note: the STRICT_MODE=False mode is also very dangerous in the case of disomogeneous property coverage by engines. With that I mean that if one engine does not overwrite all the properties pertaining to a given level of theory, a natural ambiguity arises about the data origin. Only an user familiar with the code structure can spot the difference.

As an example, building on the one presented before, consider this:

from spycci.systems import System
from spycci.engines.xtb import XtbInput
from spycci.engines.orca import OrcaInput

mol = System("water.xyz", 0, 1)

xtb = XtbInput()
orca = OrcaInput(method="PBE", basis_set="def2-SVP")

orca.freq(mol, ncores=4, inplace=True)
xtb.freq(mol, ncores=4, inplace=True)


print(mol.properties.level_of_theory_electronic)
print(mol.properties.level_of_theory_vibronic)
print(mol.properties.vibronic_energy)
if mol.properties.vibrational_data:
    print(mol.properties.vibrational_data.frequencies[-1])
else:
    print("None")

Running with STRICT_MODE=False the output is:

Undefined
Undefined
0.001986858689
3868.53

Running with STRICT_MODE=True the output is:

XtbInput || method: gfn2 | solvent: None
XtbInput || method: gfn2 | solvent: None
0.001986858689
None

This behavior is due to the fact that the xtb engine currently does not implement a parser for vibrational frequencies. The user however has no way of knowing, beside reviewing the code structure, that the frequencies computed by orca and not overwritten by xtb. I think that this should be avoided at all costs.

[AresValley]

Yes, perhaps my previous response was a bit superficial, but I also support keeping the mixed mode as described by @lbabetto (in fact, that’s exactly the behavior expected when using STRICT=True). Even more so, I agree with the idea of computing geometries at one level of theory and electronic properties with another one since I’ve used this approach many times in the past. So, in principle, I find both STRICT and VERY_STRICT modes perfectly reasonable.

What I was referring to, instead, concerns only the STRICT=False mode, where @ppravatto clearly pointed out all the issues involved, issues I fully agree with. As I mentioned earlier, I currently don't see (maybe I'm just wrong) any practical use case for working with STRICT mode disabled.

Anyway, I believe it's a good idea to inform the user about the selected STRICT mode. This is especially important if we decide to keep (hopefully not) the STRICT=False mode: the user must be 100% fully aware (!) of the heterogeneity of the data being collected, which results from using different levels of theory and the potential artifacts that may arise because of that.

[lbabetto]

In fact, with STRICT_MODE=True, users can already perform calculations involving up to three distinct levels of theory: one for geometry, one for vibrational analysis, and one for electronic structure. This is exactly the kind of setup you described (e.g., DFT for vibrations and CCSD for energies), and it’s also the default behavior in SPyCCI today.

Okay sorry, I misunderstood how this mode is applied then, my bad.

As you can see in both cases different levels of theory are used for vibronic and electronic part. In the second case however the vibrational properties computed by orca are kept with those computed by xtb with an Undefined level of theory. I find this behavior not very useful and kind of dangerous.

Yes, this is absolutely undesirable behaviour, I don't see any reasonable application for which you'd want to do this.

In fact, I would say that mixing different levels of theory for different properties is not running in STRICT mode, where I would expect all my data to come from a homogeneous level of theory.

With this in mind, I agree we should ditch completely the current state of STRICT=False and maybe implement strict mode as follows:

• STRICT = True: requires equality across geometry, electronic, and vibronic levels of theory.
• STRICT = False (default): allow different levels of theory for different properties, provided no conflicts arise, otherwise refuse to mix

So, the old STRICT actually becomes the "relaxed" mode and is set as default, while the actually strict mode does not allow any kind of mix-and-match.

[lbabetto]

I would not set STRICT as the default, since in many cases (like TD-DFT, not yet implemented but hopefully available sometimes soon) you might want to calculate the geometry with a certain functional and the excitations only at another.

[AresValley]

With this in mind, I agree we should ditch completely the current state of STRICT=False and maybe implement strict mode as follows:

STRICT = True: requires equality across geometry, electronic, and vibronic levels of theory.
STRICT = False (default): allow different levels of theory for different properties, provided no conflicts arise, otherwise refuse to mix
So, the old STRICT actually becomes the "relaxed" mode and is set as default, while the actually strict mode does not allow any kind of mix-and-match.

Yep, I really like your solution! If we proceed to the removal of the actual STRICT = False behaviour (and I believe I understood that we all agree), there is no reason to keep the VERY_STRICT definition.

[ppravatto]

Yes I agree, I think that maybe we can even structure the strictness control on three levels:

• Default: allow different levels of theory for different properties, provided no conflicts arise, otherwise refuse to mix.
• STRICT: requires equality across electronic and vibronic levels of theory.
• VERY_STRICT: requires equality across geometry, electronic, and vibronic levels of theory.

I think that this can be easily implemented and covers all possible necessity of the user.

[ppravatto]

*****************************************************
*                     SUCCESS                       *
*     DISCUSSION CONVERGED AFTER   9 COMMENTS       *
*****************************************************

 MOVING DISCUSSION TO ISSUE PAGE FOR IMPLEMENTATION