pymatgen 2025.5.28

v2025.5.28

on Python PyPI

• 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

• 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

• 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

• 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

• 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.

• 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

• 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

• 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).

• Revised typing for updated mypy criteria
• Support for parsing JDFTx AIMD files
• Expanded input tag support

• 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

• 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

• Added missing DFT functional names
• Added missing subtags for elec-minimize