Add backward compatibility for deprecated <material_overrides> XML schema

Both Python and C++ now accept the old <material_overrides> format with
a DeprecationWarning/warning() instead of a hard error, converting each
<cell_override> into an equivalent DAGMCCell or MaterialOverrides entry.

- Python: replace the ValueError in DAGMCUniverse.from_xml_element with
  a DeprecationWarning; add _parse_legacy_material_overrides() which
  builds DAGMCCell objects from <cell_override id> / <material_ids> text
- C++: replace the fatal_error in DAGUniverse XML constructor with a
  warning() + conversion loop into material_overrides map
- Both sides raise an error if <material_overrides> and <cell> appear
  together on the same <dagmc_universe>
- Replace test_dagmc_xml_reject_legacy_material_overrides with six new
  tests covering single-material, distribmat, void, both-raises,
  deprecation-warning, and round-trip-to-new-format scenarios

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: pshriwise

openmc/dagmc.py

@@ -480,16 +480,43 @@ def from_xml_element(cls, elem, mats=None):
         out.auto_geom_ids = bool(get_text(elem, "auto_geom_ids"))
         out.auto_mat_ids = bool(get_text(elem, "auto_mat_ids"))
 
-        if elem.find('material_overrides') is not None:
-            raise ValueError(
-                "DAGMCUniverse <material_overrides> is no longer supported. "
-                "Use nested <cell> elements under <dagmc_universe> instead.")
+        has_overrides = elem.find('material_overrides') is not None
+        has_cells = elem.find('cell') is not None
 
-        if elem.find('cell') is not None:
+        if has_overrides and has_cells:
+            raise ValueError(
+                "DAGMCUniverse cannot specify both <material_overrides> and "
+                "<cell> sub-elements. Use <cell> elements only.")
+
+        if has_overrides:
+            warnings.warn(
+                "DAGMCUniverse <material_overrides> is deprecated and will be "
+                "removed in a future version. Use nested <cell> elements "
+                "instead.", DeprecationWarning, stacklevel=2)
+            out._parse_legacy_material_overrides(elem, mats)
+        elif has_cells:
             out._parse_cell_overrides(elem, mats)
 
         return out
 
+    def _parse_legacy_material_overrides(self, elem, mats):
+        """Parse the deprecated <material_overrides> XML format and populate
+        the universe with equivalent DAGMCCell objects."""
+        if mats is None:
+            raise ValueError(
+                "DAGMC material overrides found but no materials were "
+                "provided to populate the mapping.")
+        mo_elem = elem.find('material_overrides')
+        for co_elem in mo_elem.findall('cell_override'):
+            cell_id = int(get_text(co_elem, 'id'))
+            mat_ids = co_elem.find('material_ids').text.split()
+            fill_objs = [mats[mid] for mid in mat_ids]
+            fill = fill_objs[0] if len(fill_objs) == 1 else fill_objs
+            if cell_id in self.cells:
+                raise ValueError(
+                    f"Duplicate DAGMC cell override specified for cell {cell_id}.")
+            self.add_cell(DAGMCCell(cell_id=cell_id, fill=fill))
+
     def _parse_cell_overrides(self, elem, mats):
         if mats is None:
             raise ValueError("DAGMC cell overrides found in DAGMC universe but "

src/dagmc.cpp

@@ -132,9 +132,22 @@ DAGUniverse::DAGUniverse(pugi::xml_node node)
       }
     }
   } else if (check_for_node(node, "material_overrides")) {
-    fatal_error(
-      "DAGMCUniverse <material_overrides> is no longer supported. Use nested "
-      "<cell> elements under <dagmc_universe> instead.");
+    if (node.child("cell")) {
+      fatal_error("DAGMCUniverse cannot specify both <material_overrides> and "
+                  "<cell> sub-elements. Use <cell> elements only.");
+    }
+    warning("DAGMCUniverse <material_overrides> is deprecated. Use nested "
+            "<cell> elements under <dagmc_universe> instead.");
+    for (pugi::xml_node co :
+      node.child("material_overrides").children("cell_override")) {
+      int32_t cell_id = std::stoi(get_node_value(co, "id"));
+      std::istringstream iss(co.child("material_ids").text().get());
+      vector<int32_t> mats;
+      for (std::string s; iss >> s;) {
+        mats.push_back(s == "void" ? MATERIAL_VOID : std::stoi(s));
+      }
+      material_overrides.emplace(cell_id, mats);
+    }
   }
 
   initialize(material_overrides, temperature_overrides, density_overrides);

tests/unit_tests/dagmc/test_model.py

@@ -319,19 +319,88 @@ def test_dagmc_xml_reject_region_override():
         openmc.DAGMCUniverse.from_xml_element(elem, mats)
 
 
-def test_dagmc_xml_reject_legacy_material_overrides():
-    mats = {'1': openmc.Material(1), 'void': None}
+def _legacy_xml(cell_overrides):
+    """Helper to build a <dagmc_universe> with old-format <material_overrides>."""
+    inner = ''.join(
+        f'<cell_override id="{cid}"><material_ids>{mids}</material_ids></cell_override>'
+        for cid, mids in cell_overrides.items()
+    )
+    return ET.fromstring(
+        f'<dagmc_universe id="1" filename="dagmc.h5m">'
+        f'<material_overrides>{inner}</material_overrides>'
+        f'</dagmc_universe>'
+    )
+
+
+def test_dagmc_xml_legacy_single_material_compat():
+    mat = openmc.Material(1)
+    mats = {'1': mat, 'void': None}
+    elem = _legacy_xml({3: '1'})
+    with pytest.warns(DeprecationWarning, match="deprecated"):
+        univ = openmc.DAGMCUniverse.from_xml_element(elem, mats)
+    assert 3 in univ.cells
+    assert univ.cells[3].fill is mat
+
+
+def test_dagmc_xml_legacy_distribmat_compat():
+    mat1, mat2 = openmc.Material(2), openmc.Material(3)
+    mats = {'2': mat1, '3': mat2, 'void': None}
+    elem = _legacy_xml({5: '2 3'})
+    with pytest.warns(DeprecationWarning):
+        univ = openmc.DAGMCUniverse.from_xml_element(elem, mats)
+    assert univ.cells[5].fill_type == 'distribmat'
+    assert list(univ.cells[5].fill) == [mat1, mat2]
+
+
+def test_dagmc_xml_legacy_void_compat():
+    mats = {'void': None}
+    elem = _legacy_xml({7: 'void'})
+    with pytest.warns(DeprecationWarning):
+        univ = openmc.DAGMCUniverse.from_xml_element(elem, mats)
+    assert univ.cells[7].fill_type == 'void'
+
+
+def test_dagmc_xml_legacy_both_raises():
+    mat = openmc.Material(1)
+    mats = {'1': mat, 'void': None}
     elem = ET.fromstring(
         '<dagmc_universe id="1" filename="dagmc.h5m">'
         '<material_overrides>'
-        '<cell_override id="1"><material_ids>1</material_ids></cell_override>'
+        '<cell_override id="3"><material_ids>1</material_ids></cell_override>'
         '</material_overrides>'
+        '<cell id="5" material="1"/>'
         '</dagmc_universe>'
     )
-    with pytest.raises(ValueError, match="no longer supported"):
+    with pytest.raises(ValueError, match="both"):
         openmc.DAGMCUniverse.from_xml_element(elem, mats)
 
 
+def test_dagmc_xml_legacy_deprecation_warning():
+    mats = {'1': openmc.Material(1), 'void': None}
+    elem = _legacy_xml({3: '1'})
+    with pytest.warns(DeprecationWarning):
+        openmc.DAGMCUniverse.from_xml_element(elem, mats)
+
+
+def test_dagmc_xml_legacy_roundtrip():
+    """Old-format XML loads correctly and re-exports using the new <cell> format."""
+    mat = openmc.Material(1)
+    mats = {'1': mat, 'void': None}
+    elem = _legacy_xml({3: '1'})
+    with pytest.warns(DeprecationWarning):
+        univ = openmc.DAGMCUniverse.from_xml_element(elem, mats)
+
+    root = ET.Element('geometry')
+    univ.create_xml_subelement(root)
+    dagmc_elem = root.find('dagmc_universe')
+
+    assert dagmc_elem.find('material_overrides') is None
+    cell_elems = dagmc_elem.findall('cell')
+    assert len(cell_elems) == 1
+    assert int(cell_elems[0].get('id')) == 3
+    assert cell_elems[0].get('material') == '1'
+
+
 def test_dagmc_xml_temperature_roundtrip():
     mat = openmc.Material(1)
     mats = {'1': mat, 'void': None}