JDFTXInfile Comparison Methods (materialsproject#4416)

* Organizing `JDFTXInfile` contents

* `is_equal_to` method for AbstractTag for equality checking, default parameters for JDFTx, unwritten `is_comparable_to` method for `JDFTXInfile`

* `get_tag_object_on_val` alternative to `get_tag_object` that auto-sets format option for `MultiformatTag`s

* Fixing value types in default inputs, repeatable multiformattags to be set as a list with elements of different format options, changing `JDFTXStructure.get_str` to build a dictionary representation of each ion instead of a list (not sure how it was even working before)

* changing `is_equal_to` to be defined in `AbstractTag` as a repeatability handler, and now `_is_equal_to` to the abstractmethod to be implemented which compares two non-list values

* Series of methods for gathering differing tags between two JDFTXInfile objects, along convenience arguments to filter which tags to pay attention to. Not sure if `is_comparable_to` is implementable in a way generalizable enough to be useful.

* typing check

* Adding back for now, seems bloaty but could be helpful for readability in implementations

* Removing commented out code

* Changing my mind about ion-species inclusion as a default ensure_include_tag

* reordering

* TODOs

* TODOs

* Partial fix for setting selective_dynamics through site_properties in `JDFTXInfile.from_structure`

* mypy fix

Author: benrich37

src/pymatgen/io/jdftx/generic_tags.py

@@ -70,6 +70,56 @@ def validate_value_type(self, tag: str, value: Any, try_auto_type_fix: bool = Fa
             tuple[str, bool, Any]: The tag, whether the value is of the correct type, and the possibly fixed value.
         """
 
+    def is_equal_to(self, val1: Any | list[Any], obj2: AbstractTag, val2: Any | list[Any]) -> bool:
+        """Check if the two values are equal.
+
+        Args:
+            val1 (Any): The value of this tag object.
+            obj2 (AbstractTag): The other tag object.
+            val2 (Any): The value of the other tag object.
+
+        Returns:
+            bool: True if the two tag object/value pairs are equal, False otherwise.
+        """
+        if self.can_repeat:
+            if not obj2.can_repeat:
+                return False
+            val1 = val1 if isinstance(val1, list) else [val1]
+            val2 = val2 if isinstance(val2, list) else [val2]
+            if len(val1) != len(val2):
+                return False
+            return all(True in [self._is_equal_to(v1, obj2, v2) for v2 in val2] for v1 in val1)
+        return self._is_equal_to(val1, obj2, val2)
+
+    @abstractmethod
+    def _is_equal_to(self, val1: Any, obj2: AbstractTag, val2: Any) -> bool:
+        """Check if the two values are equal.
+
+        Used to check if the two values are equal. Assumes val1 and val2 are single elements.
+
+        Args:
+            val1 (Any): The value of this tag object.
+            obj2 (AbstractTag): The other tag object.
+            val2 (Any): The value of the other tag object.
+
+        Returns:
+            bool: True if the two tag object/value pairs are equal, False otherwise.
+        """
+
+    def _is_same_tagtype(
+        self,
+        obj2: AbstractTag,
+    ) -> bool:
+        """Check if the two values are equal.
+
+        Args:
+            obj2 (AbstractTag): The other tag object.
+
+        Returns:
+            bool: True if the two tag object/value pairs are equal, False otherwise.
+        """
+        return isinstance(self, type(obj2))
+
     def _validate_value_type(
         self, type_check: type, tag: str, value: Any, try_auto_type_fix: bool = False
     ) -> tuple[str, bool, Any]:
@@ -258,6 +308,19 @@ def validate_value_type(self, tag: str, value: Any, try_auto_type_fix: bool = Fa
         """
         return self._validate_value_type(bool, tag, value, try_auto_type_fix=try_auto_type_fix)
 
+    def _is_equal_to(self, val1: Any, obj2: AbstractTag, val2: Any) -> bool:
+        """Check if the two values are equal.
+
+        Args:
+            val1 (Any): The value of this tag object.
+            obj2 (AbstractTag): The other tag object.
+            val2 (Any): The value of the other tag object.
+
+        Returns:
+            bool: True if the two tag object/value pairs are equal, False otherwise.
+        """
+        return self._is_same_tagtype(obj2) and val1 == val2
+
     def raise_value_error(self, tag: str, value: str) -> None:
         """Raise a ValueError for the value string.
 
@@ -335,6 +398,23 @@ def validate_value_type(self, tag: str, value: Any, try_auto_type_fix: bool = Fa
         """
         return self._validate_value_type(str, tag, value, try_auto_type_fix=try_auto_type_fix)
 
+    def _is_equal_to(self, val1: Any, obj2: AbstractTag, val2: Any) -> bool:
+        """Check if the two values are equal.
+
+        Args:
+            val1 (Any): The value of this tag object.
+            obj2 (AbstractTag): The other tag object.
+            val2 (Any): The value of the other tag object.
+
+        Returns:
+            bool: True if the two tag object/value pairs are equal, False otherwise.
+        """
+        if self._is_same_tagtype(obj2):
+            if not all(isinstance(x, str) for x in (val1, val2)):
+                raise ValueError("Both values must be strings for StrTag comparison")
+            return val1.strip() == val2.strip()
+        return False
+
     def read(self, tag: str, value: str) -> str:
         """Read the value string for this tag.
 
@@ -379,6 +459,8 @@ class AbstractNumericTag(AbstractTag):
     ub: float | None = None  # upper bound
     lb_incl: bool = True  # lower bound inclusive
     ub_incl: bool = True  # upper bound inclusive
+    eq_atol: float = 1.0e-8  # absolute tolerance for equality check
+    eq_rtol: float = 1.0e-5  # relative tolerance for equality check
 
     def val_is_within_bounds(self, value: float) -> bool:
         """Check if the value is within the bounds.
@@ -425,6 +507,22 @@ def validate_value_bounds(
             return False, self.get_invalid_value_error_str(tag, value)
         return True, ""
 
+    def _is_equal_to(self, val1, obj2, val2):
+        """Check if the two values are equal.
+
+        Used to check if the two values are equal. Doesn't need to be redefined for IntTag and FloatTag.
+
+        Args:
+            val1 (Any): The value of this tag object.
+            obj2 (AbstractTag): The other tag object.
+            val2 (Any): The value of the other tag object.
+            rtol (float, optional): Relative tolerance. Defaults to 1.e-5.
+            atol (float, optional): Absolute tolerance. Defaults to 1.e-8.
+        Returns:
+            bool: True if the two tag object/value pairs are equal, False otherwise.
+        """
+        return self._is_same_tagtype(obj2) and np.isclose(val1, val2, rtol=self.eq_rtol, atol=self.eq_atol)
+
 
 @dataclass
 class IntTag(AbstractNumericTag):
@@ -620,6 +718,10 @@ def get_token_len(self) -> int:
         """
         return self._get_token_len()
 
+    def _is_equal_to(self, val1, obj2, val2):
+        return True  # TODO: We still need to actually implement initmagmom as a multi-format tag
+        # raise NotImplementedError("equality not yet implemented for InitMagMomTag")
+
 
 @dataclass
 class TagContainer(AbstractTag):
@@ -1013,6 +1115,28 @@ def get_dict_representation(self, tag: str, value: list) -> dict | list[dict]:
         list_value = self._make_str_for_dict(tag, value)
         return self.read(tag, list_value)
 
+    def _is_equal_to(self, val1, obj2, val2):
+        """Check if the two values are equal.
+
+        Return False if (checked in following order)
+        - obj2 is not a TagContainer
+        - all of val1's subtags are not in val2
+        - val1 and val2 are not the same length (different number of subtags)
+        - at least one subtag in val1 is not equal to the corresponding subtag in val2
+        """
+        if self._is_same_tagtype(obj2):
+            if isinstance(val1, dict) and isinstance(val2, dict):
+                if all(subtag in val2 for subtag in val1) and (len(list(val1.keys())) == len(list(val2.keys()))):
+                    for subtag, subtag_type in self.subtags.items():
+                        if (subtag in val1) and (
+                            not subtag_type.is_equal_to(val1[subtag], obj2.subtags[subtag], val2[subtag])
+                        ):
+                            return False
+                    return True
+                return False
+            raise ValueError("Values must be in dictionary format for TagContainer comparison")
+        return False
+
 
 # TODO: Write StructureDefferedTagContainer back in (commented out code block removed
 # on 11/4/24) and make usable for tags like initial-magnetic-moments
@@ -1162,6 +1286,9 @@ def get_token_len(self) -> int:
         """
         raise NotImplementedError("This method is not supposed to be called directly on MultiformatTag objects!")
 
+    def _is_equal_to(self, val1, obj2, val2):
+        raise NotImplementedError("This method is not supposed to be called directly on MultiformatTag objects!")
+
 
 @dataclass
 class BoolTagContainer(TagContainer):