v2025.5.28

• PR #4411 Add orjson as required dependency as default JSON handler when custom encoder/decoder is not needed by @DanielYang59
• PR #4417 adding radd dunder method to Volumetric data + test_outputs by @wladerer
• PR #4418 JDFTXOutfileSlice Durability Improvement by @benrich37
  Major changes:
  • feature 1: Improved durability of JDFTXOutfileSlice._from_out_slice method (less likely to error out on unexpected termination)
    -- So long as one step of electronic minimization has started on an out file slice, parsing shouldn't error out
  • fix 1: Allow partially dumped eigstats
  • fix 2: Added missing optical band gap dumped by eigstats
  • fix 3: Protect the final JOutStructure in initializing a JOutStructures with a try/except block
  • fix 4: Detect if positions were only partially dumped and revert to data from init_structure in JOutStructure
  • fix 5: Prevent partially dumped matrices from being used in initializing a JOutStructure

  Todos

  • feature 1: Ensure parse-ability as long as a JDFTXOutfileSlice.infile can be initialized
• PR #4419 Fix Molecule.get_boxed_structure when reorder=False by @gpetretto
• PR #4416 JDFTXInfile Comparison Methods by @benrich37
  Major changes:
  • feature 1: Convenience methods for comparing JDFTXInfile objects
    -- JDFTXInfile.is_comparable_to
    --- Returns True if at least one tag is found different
    --- Optional arguments exclude_tags, exclude_tag_categories, ensure_include_tags to ignore certain tags in the comparison
    ---- exclude_tag_categories defaults to ["export", "restart", "structure"] as "export" and "restart" are very rarely pertinent to comparability, "structure" as subtags of this category are generally the one thing being intentionally changed in comparisons (ie different local minima or a slab with/without an adsorbate)
    -- JDFTXInfile.get_filtered_differing_tags
    --- What is used in JDFTXInfile.is_comparable_to to get filtered differing tags between JDFTXInfile objects
    --- Convenient as a "verbose" alternative to JDFTXInfile.is_comparable_to
    -- AbstractTag.is_equal_to and AbstractTag._is_equal_to
    --- Used in tag comparison for finding differing tags
    --- AbstractTag._is_equal_to is an abstract method that must be implemented for each AbstractTag inheritor
  • feature 2: Default JDFTXInfile object pymatgen.io.jdftx.inputs.ref_infile
    -- Initialized from reading default JDFTx settings from pymatgen.io.jdftx.jdftxinfile_default_inputs.default_inputs: dict
    -- Used in JDFTXInfile.get_differing_tags_from for tags in self missing from other that are identical to the default setting
  • fix 1: Re-ordered contents of JDFTXInfile to follow the order: magic methods -> class methods / transformation methods -> validation methods -> properties -> private methods
  • fix 2: Checking for 'selective_dynamics' in site_properties for a Structure passed in JDFTXInfile.from_structure (used if selective_dynamics argument left as None)

  Todos

  • feature 1: Add examples to documentation on how to properly use new comparison methods
  • feature 2: Improve the mapping of TagContainers to their default values
    -- The current implementation of comparison for tags to default values only works if the tag as written exactly matches the full default value - at the very least the missing subtags of a partially filled TagContainer needs to be filled with the default values before comparing to the full default value
    -- Some subtags also change depending on the other subtags present for a particular tag (ie convergence threshold depending on algorithm specified for 'fluid-minimize', so an improved mapping for dynamic default values needs to be implemented
• PR #4413 JDFTXOutputs.bandstructure: BandStructure by @benrich37
  Major changes:
  • feature 1: Added 'kpts' storable variable to JDFTXOutputs
    -- Currently only able to obtain from the 'bandProjections' file
  • feature 2: Added bandstructure attribute to JDFTXOutputs
    -- Standard pymatgen BandStrucure object
    -- Request-able as a store_var, but functions slightly differently
    --- Ensures 'eigenvals' and 'kpts' are in store_vars and then is deleted
    -- Initialized if JDFTXOutputs has successfully stored at least 'kpts' and 'eigenvals'
    -- Fills projections field if also has stored 'bandProjections'
  • feature 3: Added wk_list to JDFTXOutputs
    -- List of weights for each k-point
    -- Currently doesn't have a use, but will be helpful for ElecData initializing in crawfish

  Todos

  • feature 1: Add reading 'kpts' from the standalone 'kPts' file dumped by JDFTx
  • feature 2: Outline how we might initialize BandStructureSymmLine(s) for calculations with explicitly defined 'kpoint' tags, as using 'kpoint's instead of kpoint-folding is most likely an indicator of a band-structure calculation
• PR #4415 speed-up Structure instantiation by @danielzuegner
  This PR speeds up the instantiation of Structure objects by preventing hash collisions in the lru_cache of get_el_sp and increasing its maxsize. The issue is that currently Element objects are hashed to the same value as the integer atomic numbers (e.g., Element[H] maps to the same hash as int(1)). This forces the lru_hash to perform an expensive __eq__ comparison between the two, which reduces the performance of instantiating many Structure objects. Also here we increase the maxsize of get_el_sp's lru_cache to 1024 for further performance improvements.
  This reduces time taken to instantiate 100,000 Structure objects from 31 seconds to 8.7s (avoid hash collisions) to 6.1s (also increase maxsize to 1024).
• PR #4410 JDFTx Inputs - boundary value checking by @benrich37
  Major changes:
  • feature 1: Revised boundary checking for input tags
    -- Added a validate_value_bounds method to AbstractTag, that by default always returns True, ""
    -- Added an alternate AbstractNumericTag that inherits AbstractTag to implement validate_value_bounds properly
    --- Changed boundary storing to the following fields
    ---- ub and lb
    ----- Can either be None, or some value to indicate an upper or lower bound
    ---- ub_incl and lb_incl
    ----- If True, applies >= instead of > in comparative checks on upper and lower bounds
    -- Switched inheritance of FloatTag and IntTag from AbstractTag to AbstractNumericTag
    -- Implemented validate_value_bounds for TagContainer to dispatch checking for contained subtags
    -- Added a method validate_boundaries to JDFTXInfile to run validate_value_bounds on all contained tags and values
    -- Added validate_value_boundaries argument for initialization methods of JDFTXInfile, which will run validate_boundaries after initializing JDFTXInfile but before returning when True
    --- Note that this is explicitly disabled when initializing a JDFTXInfile from the input summary in a JDFTXOutfileSlice - boundary values may exist internally in JDFTx for non-inclusive bounded tags as the default values, but cannot be passed in the input file. For this reason, errors on boundary checking must be an easily disabled feature for the construction and manipulation of a JDFTXInfile, but out-of-bounds values must never be written when writing a file for passing to JDFTx.

  Todos

  • feature 1
    -- Implement some way boundary checking can run when adding tags to a pre-existing JDFTXInfile object
    --- boundary checking is currently only run when initializing from a pre-existing collection of input tags
    --- writing this into JDFTXInfile.__setitem__ is too extreme as it would require adding an attribute to JDFTXInfile to allow disabling the check
    --- the better solution would be to implement a more obvious user-friendly method for reading in additional inputs so that the user doesn't need to learn how to properly write out the dictionary representation of complicated tag containers.
    -- Fill out reference tags for other unimplemented boundaries
• PR #4408 to_jdftxinfile method for JDFTXOutfile by @benrich37
  Major changes:
  • feature 1: Method to_jdftxinfile for JDFTXOutfile(Slice)
    -- Uses internal JDFTXInfile and Structure to create a new JDFTXInfile object that can be ran to restart a calculation
  • feature 2: Method strip_structure_tags for JDFTXInfile
    -- Strips all structural tags from a JDFTXInfile for creating equivalent JDFTXInfile objects with updated associated structures
  • fix 1: Changing 'nAlphaAdjustMax' shared tag from a FloatTag to an IntTag
  • fix 2: Adding an optional minval field for certain FloatTags which prevent writing error-raising values
    -- Certain tag options in JDFTx can internally be the minimum value, but trying to pass the minimum value will raise an error

  Todos

  • feature 1: Testing for the to_jdftxinfile
    -- I know the function works from having used it, but I haven't written in an explicit test for it yet.
  • fix 2: Look through JDFTx source code and identify all the numeric tag value boundaries and add them to the FloatTag. This will likely require generalizing how boundaries are tested as a quick glance (see here) shows there are tags that actually do use the >= operator
  • Unrelated: Reduce bloat in outputs module
    -- Remove references to deprecated fields
    -- Begin phasing out redundant fields
    --- i.e. JDFTXOutfile.lattice redundant to JDFTXOutfile.structure.lattice.matrix
    -- Generalize how optimization logs are stored in outputs module objects
    --- Fields like grad_K are part of a broad group of values that can be logged for an optimization step, and the fields present in each log varies a lot more than I previously thought when I initially wrote the JDFTx outputs module. Generalizing how these are stored into a dictionary of arbitrary keys should make the outputs module more robust, as well as helping reduce the bloat in the outputs module.
• PR #4407 JDFTXInfile addition (__add__) method tweak by @benrich37
  Changing addition method - now infiles with shared keys will either concatenate their inputs if the key is for a repeatable tag, or change to whatever value is in the second infile if it is not a repeatable tag. A bare minimum if subval in params[key] check is done to avoid adding duplicate values. This seems like something the set built-in could help with, but since the sub-values are dictionaries, using set is a little more difficult
  Major changes:
  • fix 1: Addition of two JDFTXInfiles (jif1 = jif2 + jif3) no longer requires each jif2 and jif3 to have a unique set of tags
    -- For a non-repeatable tag 'key', jif1['key'] == jif3['key']
    -- For a repeatable-tag 'key', jif1['key'] = jif2['key'] + [val for val in jif3['key'] if not val in jif2['key']
    -- implemented in src/pymatgen/io/jdftx/inputs.py
    -- tested in tests/io/jdftx/test_jdftxinfile.py
    --- error raising test for conflicting tag values removed

  Todos

  • fix 1: Add more robust checking for if two repeatable tag values represent the same information.
    -- This is likely fixed by implementing the pre-existing TODO - "Add default value filling like JDFTx does"
  • fix 2: Incorporate something to collapse repeated dump tags of the same frequency into a single value.
    -- The 'dump' tag currently can get bloated very quickly, as the newly implemented change for concatenating two repeatable tags will not detect that something like {"End": {"State": True}} is technically already in a list that contains something like {"End": {"State": True, "Berry": True}}
    -- A cleanup function that can convert {'dump': [{"End": {"State": True, "BGW": True}}, {"End": {"State": True, "Berry": True}}] into {'dump': [{"End": {"State": True, "BGW": True, "Berry": True}}] would fix this bloat risk
• PR #4404 Monoclinic Symmetry Handling Fix by @kavanase
  This issue is related to #1929 (for which a patch solution was added that fixed one case of this occurrence, but not in general).
  When handling monoclinic symmetry within SpacegroupAnalyzer, the standardisation attempts to reorder the lattice vectors depending on whether the alpha angle is >90 degrees or <90 degrees. If it is exactly 90 degrees, it defaults to the original lattice, however there was an issue with this implementation where it assumed that the beta and gamma angles were also 90 degrees (and so set the lattice matrix as [[a, 0, 0], [0, b, 0], [0, 0, c]]), which may not (and in most cases should not) be the case.
  This was causing weird behaviour for me where the volume of the primitive structures being returned by SpacegroupAnalyzer was different to Structure.find_primitive() (by a non-integer factor). I've added a test for this case, and also confirmed that the general implementation here works for the failure case noted in #1929
• PR #4406 UFloat update by @kavanase
  This is a minor addition to #4400.
  I found that there were some cases where an energy adjustment of UFloat(0, 0) were already present in ComputedEntry.energy_adjustments, avoiding the updated handling of setting std_dev to np.nan when it is 0 (and avoiding the UFloat warning about std_dev being 0).
• PR #4403 Ensure structure symmetrization in OrderDisorderedStructureTransformation by @esoteric-ephemera
  Close #4402 by ensuring that structures are always symmetrized when symmetrized_structures = True in OrderDisorderedStructureTransformation. Also allow for passing distance/angle precision kwargs to do on-the-fly symmetrization. Add tests
• PR #4401 JDFTXStructure - partial fix for special case lattice tags by @benrich37
  Major changes:
  • fix 1: pymatgen.io.jdftx.inputs.JDFTXStructure
    -- JDFTXStructure.from_jdftxinfile no longer assumes 'lattice' tag is provided in 3x3 matrix format
    -- Testing in tests/io/jdftx/test_jdftxinfile.py for Structure <-> JDFTXStructure <-> JDFTXInfile conversion for JDFTXInfile with newly implemented special case values for 'lattice' tag
    TODO:
  • Implement JDFTXStructure.from_jdftxinfile for JDFTXInfile with special case tag 'lattice' value and non-identity value for 'latt-scale' tag
• PR #4400 Use np.nan instead of 0 for no uncertainty with ufloat, to avoid unnecessary warnings by @kavanase
  Closes #4386
• PR #4399 JDFTXOutfile none_on_error oversight fix by @benrich37
  • Fixing an error in pymatgen/io/jdftx/outputs.py that causes construction of a JDFTXOutfile to fail if none_on_error is turned on and the final JDFTXOutfileSlice in slices is None (ie a very common issue when parsing an interrupted job that hasn't restarted yet).
• PR #4397 JDFTx IO Module Overhaul by @benrich37
  • Revised typing for updated mypy criteria
  • Support for parsing JDFTx AIMD files
  • Expanded input tag support
• PR #4394 Updates to JDFTx inputs generic_tags helper module by @benrich37
  Major changes:
  • Phasing out use of redundant TagContainer.multiline_tag attribute
    -- (this change may cause problems without the corresponding changes in jdftxinfile_master_format.py, but all the tests still pass. Just in case, I will be prioritizing finishing merges for the JDFTx inputs module to avoid any untested consequences)
  • Fixing indentation on output of TagContainer.write
  • Removing the warning (and the test for this warning) on special constraints for "ion" tag
    -- Support for special constraints has been implemented on my fork and a PR for this support will soon be created
• PR #4392 Brute force order matcher speedup by @kavanase
  This is a small PR to add a break_on_tol option to BruteForceOrderMatcher, which allows one to massively speed up the molecule matching in cases where one just cares if the molecules match within a given RMSD (rather than screening over all possible permutations, to get the lowest possible RMSD).
  The speedup factor can be anywhere from 0% to several orders of magnitude, depending on the number of possible permutations and when a matching permutation is found.
  Also includes a small typo fix that for an error message that reference the original class name (in #1938) which was later renamed.
  I've also added some tests for this.
• PR #4393 Update JDFTx IO output utils private module by @benrich37
  Major changes:
  • function get_colon_var_t1
    -- Renaming to get_colon_val, but keeping an alias until renaming is updated outside this module
    -- Returning np.nan instead of None when "nan" is the value
  • updating correct_geom_opt_type for working with JDFTx AIMD out files
  • updating typing on array-construction functions
  • correcting ordering and syntax of orbital labels to exactly match JDFTx
• PR #4389 Adding missing reference options to JDFTx inputs submodule by @benrich37
  Beginning process of merging over stress-test updates, starting with missing options for JDFTx input files
  • Added missing DFT functional names
  • Added missing subtags for elec-minimize