Add cell_wise MGXS generation method

[jon-proximafusion]

Add a cell_wise MGXS generation method

model.convert_to_multigroup(method="cell_wise", groups=...)

Like material_wise, but gives each cell its own multigroup cross sections, so it
captures the intra-material spatial variation that material_wise averages away
(for example a steel material reused in several cells).

Implementation

Full reuse of the material_wise path. Before generation, the material in every
material-filled cell is cloned (each clone gets a unique id via
Material.clone()). The standard per-material generation then produces and assigns
one cross section set per cell. The only new code is the per-cell cloning step in
convert_to_multigroup plus the dispatch entry (about 20 lines). material_wise
behavior is unchanged.

Works for both CSG and DAGMC. convert_to_multigroup already synchronizes DAGMC
cells before generation, so the per-cell clones become standard DAGMC per-cell
material overrides with no special handling.

Contents

• openmc/model/model.py: the per-cell cloning step and dispatch entry.
• tests/unit_tests/test_model.py: CSG unit test (two cells sharing a material get
  distinct macroscopics).
• tests/unit_tests/dagmc/test_convert_to_multigroup.py: DAGMC unit test (a model
  with two fuel volumes sharing one material yields three distinct per-cell
  macroscopics).
• docs/source/usersguide/random_ray.rst: adds cell_wise to the method
  list and to the "Comparison of Automatic MGXS Generation Methods" table.

Verification

• CSG: a 4-shell single-material sphere produces four distinct per-cell cross
  section sets, while material_wise on the same model produces one (regression
  intact).
• DAGMC: the 5-volume dagmc.h5m model (two fuel volumes sharing one material,
  plus water) yields three distinct per-cell macroscopics; void volumes are
  skipped.

Status

• Based on develop (the name+id library keying from Preserve user material names in convert_to_multigroup and avoid overwriting material with same name bug fix #3984 is merged).
• Possible follow-up: distribcell (per-instance) granularity. This PR does
  per-cell-definition (one cross section set per cell, shared across lattice
  instances).

[jtramm]

This looks great @jon-proximafusion -- thanks so much for adding it in! I think it should be a cheap way of improving fidelity vs. the current material-wise method.

Just one small comment below on adding some extra clarifying discussions to the docs.

Additionally - we currently have end-to-end testing for all the MGXS generation techniques in tests/regression_tests/random_ray_auto_convert/test.py, so you could add the new method to the @parametrize list there to test it as well.

[jtramm]

We might want to add a note clarifying that it is generating unique MGXS data for each cell and not for each cell instance. Basically, it would be nice to alert the user that a cell that shows up in multiple locations of a lattice would have the same MGXS data set for all locations. If this type of discussion ends up being too wordy for the table formatting, perhaps it can be included as regular text elsewhere in the section.

• Resolves intra-material spatial variation that material_wise averages
  away, e.g. a thick shield or a steep flux gradient within a single material
• Captures spatial self shielding between cells filled with the same material

I don't completely agree with, as a cell may still be very large and have a steep gradient within it. A full shield wall may easily just be defined with one cell, in which case, you still are sharing the same MGXS throughout the full wall (even if you had applied a cell-under-voxel overlay to make smaller source regions). You only get an improvement if you had manually broken the shield wall down in your geometry definition into multiple cells that cover different depths of the wall. Basically, we don't want to oversell this method in terms of fidelity.

[shimwell]

thanks @jtramm yes good spot, I have updated the docs as suggested

[jon-proximafusion]

Thanks @jtramm, good points on both. I've pushed a doc-only commit:

• Reworded the fidelity claim so it no longer implies an arbitrary intra-cell gradient is resolved. It now states the gain is between distinct cells sharing a material, and added a cons bullet noting fidelity is bounded by the cell definitions (not the source region mesh), so a single large cell uses one cross section set throughout and a gradient is only resolved if the geometry is split into several cells.
• Added a note after the table clarifying that cell_wise generates one cross section set per cell definition, not per cell instance, so a cell repeated across lattice locations shares a single set.

[jon-proximafusion]

Add a cell_wise MGXS generation method

model.convert_to_multigroup(method="cell_wise", groups=...)

Like material_wise, but gives each cell its own multigroup cross sections, so it
captures the intra-material spatial variation that material_wise averages away
(for example a steel material reused in several cells).

Implementation

Full reuse of the material_wise path. Before generation, the material in every
material-filled cell is cloned (each clone gets a unique id via
Material.clone()). The standard per-material generation then produces and assigns
one cross section set per cell. The only new code is the per-cell cloning step in
convert_to_multigroup plus the dispatch entry (about 20 lines). material_wise
behavior is unchanged.

Works for both CSG and DAGMC. convert_to_multigroup already synchronizes DAGMC
cells before generation, so the per-cell clones become standard DAGMC per-cell
material overrides with no special handling.

Contents

• openmc/model/model.py: the per-cell cloning step and dispatch entry.
• tests/unit_tests/test_model.py: CSG unit test (two cells sharing a material get
  distinct macroscopics).
• tests/unit_tests/dagmc/test_convert_to_multigroup.py: DAGMC unit test (a model
  with two fuel volumes sharing one material yields three distinct per-cell
  macroscopics).
• docs/source/usersguide/random_ray.rst: adds cell_wise to the method
  list and to the "Comparison of Automatic MGXS Generation Methods" table.

Verification

• CSG: a 4-shell single-material sphere produces four distinct per-cell cross
  section sets, while material_wise on the same model produces one (regression
  intact).
• DAGMC: the 5-volume dagmc.h5m model (two fuel volumes sharing one material,
  plus water) yields three distinct per-cell macroscopics; void volumes are
  skipped.

Status

• Based on develop (the name+id library keying from Preserve user material names in convert_to_multigroup and avoid overwriting material with same name bug fix #3984 is merged).
• Possible follow-up: distribcell (per-instance) granularity. This PR does
  per-cell-definition (one cross section set per cell, shared across lattice
  instances).

[jtramm]

This looks great @jon-proximafusion -- thanks so much for adding it in! I think it should be a cheap way of improving fidelity vs. the current material-wise method.

Just one small comment below on adding some extra clarifying discussions to the docs.

Additionally - we currently have end-to-end testing for all the MGXS generation techniques in tests/regression_tests/random_ray_auto_convert/test.py, so you could add the new method to the @parametrize list there to test it as well.

[jtramm]

We might want to add a note clarifying that it is generating unique MGXS data for each cell and not for each cell instance. Basically, it would be nice to alert the user that a cell that shows up in multiple locations of a lattice would have the same MGXS data set for all locations. If this type of discussion ends up being too wordy for the table formatting, perhaps it can be included as regular text elsewhere in the section.

• Resolves intra-material spatial variation that material_wise averages
  away, e.g. a thick shield or a steep flux gradient within a single material
• Captures spatial self shielding between cells filled with the same material

I don't completely agree with, as a cell may still be very large and have a steep gradient within it. A full shield wall may easily just be defined with one cell, in which case, you still are sharing the same MGXS throughout the full wall (even if you had applied a cell-under-voxel overlay to make smaller source regions). You only get an improvement if you had manually broken the shield wall down in your geometry definition into multiple cells that cover different depths of the wall. Basically, we don't want to oversell this method in terms of fidelity.

[shimwell]

thanks @jtramm yes good spot, I have updated the docs as suggested

[jon-proximafusion]

Thanks @jtramm, good points on both. I've pushed a doc-only commit:

• Reworded the fidelity claim so it no longer implies an arbitrary intra-cell gradient is resolved. It now states the gain is between distinct cells sharing a material, and added a cons bullet noting fidelity is bounded by the cell definitions (not the source region mesh), so a single large cell uses one cross section set throughout and a gradient is only resolved if the geometry is split into several cells.
• Added a note after the table clarifying that cell_wise generates one cross section set per cell definition, not per cell instance, so a cell repeated across lattice locations shares a single set.

[jon-proximafusion]

Add a cell_wise MGXS generation method

model.convert_to_multigroup(method="cell_wise", groups=...)

Like material_wise, but gives each cell its own multigroup cross sections, so it
captures the intra-material spatial variation that material_wise averages away
(for example a steel material reused in several cells).

Implementation

Full reuse of the material_wise path. Before generation, the material in every
material-filled cell is cloned (each clone gets a unique id via
Material.clone()). The standard per-material generation then produces and assigns
one cross section set per cell. The only new code is the per-cell cloning step in
convert_to_multigroup plus the dispatch entry (about 20 lines). material_wise
behavior is unchanged.

Works for both CSG and DAGMC. convert_to_multigroup already synchronizes DAGMC
cells before generation, so the per-cell clones become standard DAGMC per-cell
material overrides with no special handling.

Contents

• openmc/model/model.py: the per-cell cloning step and dispatch entry.
• tests/unit_tests/test_model.py: CSG unit test (two cells sharing a material get
  distinct macroscopics).
• tests/unit_tests/dagmc/test_convert_to_multigroup.py: DAGMC unit test (a model
  with two fuel volumes sharing one material yields three distinct per-cell
  macroscopics).
• docs/source/usersguide/random_ray.rst: adds cell_wise to the method
  list and to the "Comparison of Automatic MGXS Generation Methods" table.

Verification

• CSG: a 4-shell single-material sphere produces four distinct per-cell cross
  section sets, while material_wise on the same model produces one (regression
  intact).
• DAGMC: the 5-volume dagmc.h5m model (two fuel volumes sharing one material,
  plus water) yields three distinct per-cell macroscopics; void volumes are
  skipped.

Status

• Based on develop (the name+id library keying from Preserve user material names in convert_to_multigroup and avoid overwriting material with same name bug fix #3984 is merged).
• Possible follow-up: distribcell (per-instance) granularity. This PR does
  per-cell-definition (one cross section set per cell, shared across lattice
  instances).

[jtramm]

This looks great @jon-proximafusion -- thanks so much for adding it in! I think it should be a cheap way of improving fidelity vs. the current material-wise method.

Just one small comment below on adding some extra clarifying discussions to the docs.

Additionally - we currently have end-to-end testing for all the MGXS generation techniques in tests/regression_tests/random_ray_auto_convert/test.py, so you could add the new method to the @parametrize list there to test it as well.

[jtramm]

We might want to add a note clarifying that it is generating unique MGXS data for each cell and not for each cell instance. Basically, it would be nice to alert the user that a cell that shows up in multiple locations of a lattice would have the same MGXS data set for all locations. If this type of discussion ends up being too wordy for the table formatting, perhaps it can be included as regular text elsewhere in the section.

• Resolves intra-material spatial variation that material_wise averages
  away, e.g. a thick shield or a steep flux gradient within a single material
• Captures spatial self shielding between cells filled with the same material

I don't completely agree with, as a cell may still be very large and have a steep gradient within it. A full shield wall may easily just be defined with one cell, in which case, you still are sharing the same MGXS throughout the full wall (even if you had applied a cell-under-voxel overlay to make smaller source regions). You only get an improvement if you had manually broken the shield wall down in your geometry definition into multiple cells that cover different depths of the wall. Basically, we don't want to oversell this method in terms of fidelity.

[shimwell]

thanks @jtramm yes good spot, I have updated the docs as suggested

[jon-proximafusion]

Thanks @jtramm, good points on both. I've pushed a doc-only commit:

• Reworded the fidelity claim so it no longer implies an arbitrary intra-cell gradient is resolved. It now states the gain is between distinct cells sharing a material, and added a cons bullet noting fidelity is bounded by the cell definitions (not the source region mesh), so a single large cell uses one cross section set throughout and a gradient is only resolved if the geometry is split into several cells.
• Added a note after the table clarifying that cell_wise generates one cross section set per cell definition, not per cell instance, so a cell repeated across lattice locations shares a single set.

[jon-proximafusion]

Add a cell_wise MGXS generation method

model.convert_to_multigroup(method="cell_wise", groups=...)

Like material_wise, but gives each cell its own multigroup cross sections, so it
captures the intra-material spatial variation that material_wise averages away
(for example a steel material reused in several cells).

Implementation

Full reuse of the material_wise path. Before generation, the material in every
material-filled cell is cloned (each clone gets a unique id via
Material.clone()). The standard per-material generation then produces and assigns
one cross section set per cell. The only new code is the per-cell cloning step in
convert_to_multigroup plus the dispatch entry (about 20 lines). material_wise
behavior is unchanged.

Works for both CSG and DAGMC. convert_to_multigroup already synchronizes DAGMC
cells before generation, so the per-cell clones become standard DAGMC per-cell
material overrides with no special handling.

Contents

• openmc/model/model.py: the per-cell cloning step and dispatch entry.
• tests/unit_tests/test_model.py: CSG unit test (two cells sharing a material get
  distinct macroscopics).
• tests/unit_tests/dagmc/test_convert_to_multigroup.py: DAGMC unit test (a model
  with two fuel volumes sharing one material yields three distinct per-cell
  macroscopics).
• docs/source/usersguide/random_ray.rst: adds cell_wise to the method
  list and to the "Comparison of Automatic MGXS Generation Methods" table.

Verification

• CSG: a 4-shell single-material sphere produces four distinct per-cell cross
  section sets, while material_wise on the same model produces one (regression
  intact).
• DAGMC: the 5-volume dagmc.h5m model (two fuel volumes sharing one material,
  plus water) yields three distinct per-cell macroscopics; void volumes are
  skipped.

Status

• Based on develop (the name+id library keying from Preserve user material names in convert_to_multigroup and avoid overwriting material with same name bug fix #3984 is merged).
• Possible follow-up: distribcell (per-instance) granularity. This PR does
  per-cell-definition (one cross section set per cell, shared across lattice
  instances).

[jtramm]

This looks great @jon-proximafusion -- thanks so much for adding it in! I think it should be a cheap way of improving fidelity vs. the current material-wise method.

Just one small comment below on adding some extra clarifying discussions to the docs.

Additionally - we currently have end-to-end testing for all the MGXS generation techniques in tests/regression_tests/random_ray_auto_convert/test.py, so you could add the new method to the @parametrize list there to test it as well.

[jtramm]

We might want to add a note clarifying that it is generating unique MGXS data for each cell and not for each cell instance. Basically, it would be nice to alert the user that a cell that shows up in multiple locations of a lattice would have the same MGXS data set for all locations. If this type of discussion ends up being too wordy for the table formatting, perhaps it can be included as regular text elsewhere in the section.

• Resolves intra-material spatial variation that material_wise averages
  away, e.g. a thick shield or a steep flux gradient within a single material
• Captures spatial self shielding between cells filled with the same material

I don't completely agree with, as a cell may still be very large and have a steep gradient within it. A full shield wall may easily just be defined with one cell, in which case, you still are sharing the same MGXS throughout the full wall (even if you had applied a cell-under-voxel overlay to make smaller source regions). You only get an improvement if you had manually broken the shield wall down in your geometry definition into multiple cells that cover different depths of the wall. Basically, we don't want to oversell this method in terms of fidelity.

[shimwell]

thanks @jtramm yes good spot, I have updated the docs as suggested

[jon-proximafusion]

Thanks @jtramm, good points on both. I've pushed a doc-only commit:

• Reworded the fidelity claim so it no longer implies an arbitrary intra-cell gradient is resolved. It now states the gain is between distinct cells sharing a material, and added a cons bullet noting fidelity is bounded by the cell definitions (not the source region mesh), so a single large cell uses one cross section set throughout and a gradient is only resolved if the geometry is split into several cells.
• Added a note after the table clarifying that cell_wise generates one cross section set per cell definition, not per cell instance, so a cell repeated across lattice locations shares a single set.

[jon-proximafusion]

Add a cell_wise MGXS generation method

model.convert_to_multigroup(method="cell_wise", groups=...)

Like material_wise, but gives each cell its own multigroup cross sections, so it
captures the intra-material spatial variation that material_wise averages away
(for example a steel material reused in several cells).

Implementation

Full reuse of the material_wise path. Before generation, the material in every
material-filled cell is cloned (each clone gets a unique id via
Material.clone()). The standard per-material generation then produces and assigns
one cross section set per cell. The only new code is the per-cell cloning step in
convert_to_multigroup plus the dispatch entry (about 20 lines). material_wise
behavior is unchanged.

Works for both CSG and DAGMC. convert_to_multigroup already synchronizes DAGMC
cells before generation, so the per-cell clones become standard DAGMC per-cell
material overrides with no special handling.

Contents

• openmc/model/model.py: the per-cell cloning step and dispatch entry.
• tests/unit_tests/test_model.py: CSG unit test (two cells sharing a material get
  distinct macroscopics).
• tests/unit_tests/dagmc/test_convert_to_multigroup.py: DAGMC unit test (a model
  with two fuel volumes sharing one material yields three distinct per-cell
  macroscopics).
• docs/source/usersguide/random_ray.rst: adds cell_wise to the method
  list and to the "Comparison of Automatic MGXS Generation Methods" table.

Verification

• CSG: a 4-shell single-material sphere produces four distinct per-cell cross
  section sets, while material_wise on the same model produces one (regression
  intact).
• DAGMC: the 5-volume dagmc.h5m model (two fuel volumes sharing one material,
  plus water) yields three distinct per-cell macroscopics; void volumes are
  skipped.

Status

• Based on develop (the name+id library keying from Preserve user material names in convert_to_multigroup and avoid overwriting material with same name bug fix #3984 is merged).
• Possible follow-up: distribcell (per-instance) granularity. This PR does
  per-cell-definition (one cross section set per cell, shared across lattice
  instances).

[jtramm]

This looks great @jon-proximafusion -- thanks so much for adding it in! I think it should be a cheap way of improving fidelity vs. the current material-wise method.

Just one small comment below on adding some extra clarifying discussions to the docs.

Additionally - we currently have end-to-end testing for all the MGXS generation techniques in tests/regression_tests/random_ray_auto_convert/test.py, so you could add the new method to the @parametrize list there to test it as well.

[jtramm]

We might want to add a note clarifying that it is generating unique MGXS data for each cell and not for each cell instance. Basically, it would be nice to alert the user that a cell that shows up in multiple locations of a lattice would have the same MGXS data set for all locations. If this type of discussion ends up being too wordy for the table formatting, perhaps it can be included as regular text elsewhere in the section.

• Resolves intra-material spatial variation that material_wise averages
  away, e.g. a thick shield or a steep flux gradient within a single material
• Captures spatial self shielding between cells filled with the same material

I don't completely agree with, as a cell may still be very large and have a steep gradient within it. A full shield wall may easily just be defined with one cell, in which case, you still are sharing the same MGXS throughout the full wall (even if you had applied a cell-under-voxel overlay to make smaller source regions). You only get an improvement if you had manually broken the shield wall down in your geometry definition into multiple cells that cover different depths of the wall. Basically, we don't want to oversell this method in terms of fidelity.

[shimwell]

thanks @jtramm yes good spot, I have updated the docs as suggested

[jon-proximafusion]

Thanks @jtramm, good points on both. I've pushed a doc-only commit:

• Reworded the fidelity claim so it no longer implies an arbitrary intra-cell gradient is resolved. It now states the gain is between distinct cells sharing a material, and added a cons bullet noting fidelity is bounded by the cell definitions (not the source region mesh), so a single large cell uses one cross section set throughout and a gradient is only resolved if the geometry is split into several cells.
• Added a note after the table clarifying that cell_wise generates one cross section set per cell definition, not per cell instance, so a cell repeated across lattice locations shares a single set.

[jon-proximafusion]

Add a cell_wise MGXS generation method

model.convert_to_multigroup(method="cell_wise", groups=...)

Like material_wise, but gives each cell its own multigroup cross sections, so it
captures the intra-material spatial variation that material_wise averages away
(for example a steel material reused in several cells).

Implementation

Full reuse of the material_wise path. Before generation, the material in every
material-filled cell is cloned (each clone gets a unique id via
Material.clone()). The standard per-material generation then produces and assigns
one cross section set per cell. The only new code is the per-cell cloning step in
convert_to_multigroup plus the dispatch entry (about 20 lines). material_wise
behavior is unchanged.

Works for both CSG and DAGMC. convert_to_multigroup already synchronizes DAGMC
cells before generation, so the per-cell clones become standard DAGMC per-cell
material overrides with no special handling.

Contents

• openmc/model/model.py: the per-cell cloning step and dispatch entry.
• tests/unit_tests/test_model.py: CSG unit test (two cells sharing a material get
  distinct macroscopics).
• tests/unit_tests/dagmc/test_convert_to_multigroup.py: DAGMC unit test (a model
  with two fuel volumes sharing one material yields three distinct per-cell
  macroscopics).
• docs/source/usersguide/random_ray.rst: adds cell_wise to the method
  list and to the "Comparison of Automatic MGXS Generation Methods" table.

Verification

• CSG: a 4-shell single-material sphere produces four distinct per-cell cross
  section sets, while material_wise on the same model produces one (regression
  intact).
• DAGMC: the 5-volume dagmc.h5m model (two fuel volumes sharing one material,
  plus water) yields three distinct per-cell macroscopics; void volumes are
  skipped.

Status

• Based on develop (the name+id library keying from Preserve user material names in convert_to_multigroup and avoid overwriting material with same name bug fix #3984 is merged).
• Possible follow-up: distribcell (per-instance) granularity. This PR does
  per-cell-definition (one cross section set per cell, shared across lattice
  instances).

[jtramm]

This looks great @jon-proximafusion -- thanks so much for adding it in! I think it should be a cheap way of improving fidelity vs. the current material-wise method.

Just one small comment below on adding some extra clarifying discussions to the docs.

Additionally - we currently have end-to-end testing for all the MGXS generation techniques in tests/regression_tests/random_ray_auto_convert/test.py, so you could add the new method to the @parametrize list there to test it as well.

[jtramm]

We might want to add a note clarifying that it is generating unique MGXS data for each cell and not for each cell instance. Basically, it would be nice to alert the user that a cell that shows up in multiple locations of a lattice would have the same MGXS data set for all locations. If this type of discussion ends up being too wordy for the table formatting, perhaps it can be included as regular text elsewhere in the section.

• Resolves intra-material spatial variation that material_wise averages
  away, e.g. a thick shield or a steep flux gradient within a single material
• Captures spatial self shielding between cells filled with the same material

I don't completely agree with, as a cell may still be very large and have a steep gradient within it. A full shield wall may easily just be defined with one cell, in which case, you still are sharing the same MGXS throughout the full wall (even if you had applied a cell-under-voxel overlay to make smaller source regions). You only get an improvement if you had manually broken the shield wall down in your geometry definition into multiple cells that cover different depths of the wall. Basically, we don't want to oversell this method in terms of fidelity.

[shimwell]

thanks @jtramm yes good spot, I have updated the docs as suggested

[jon-proximafusion]

Thanks @jtramm, good points on both. I've pushed a doc-only commit:

• Reworded the fidelity claim so it no longer implies an arbitrary intra-cell gradient is resolved. It now states the gain is between distinct cells sharing a material, and added a cons bullet noting fidelity is bounded by the cell definitions (not the source region mesh), so a single large cell uses one cross section set throughout and a gradient is only resolved if the geometry is split into several cells.
• Added a note after the table clarifying that cell_wise generates one cross section set per cell definition, not per cell instance, so a cell repeated across lattice locations shares a single set.

[jon-proximafusion]

Add a cell_wise MGXS generation method

model.convert_to_multigroup(method="cell_wise", groups=...)

Like material_wise, but gives each cell its own multigroup cross sections, so it
captures the intra-material spatial variation that material_wise averages away
(for example a steel material reused in several cells).

Implementation

Full reuse of the material_wise path. Before generation, the material in every
material-filled cell is cloned (each clone gets a unique id via
Material.clone()). The standard per-material generation then produces and assigns
one cross section set per cell. The only new code is the per-cell cloning step in
convert_to_multigroup plus the dispatch entry (about 20 lines). material_wise
behavior is unchanged.

Works for both CSG and DAGMC. convert_to_multigroup already synchronizes DAGMC
cells before generation, so the per-cell clones become standard DAGMC per-cell
material overrides with no special handling.

Contents

• openmc/model/model.py: the per-cell cloning step and dispatch entry.
• tests/unit_tests/test_model.py: CSG unit test (two cells sharing a material get
  distinct macroscopics).
• tests/unit_tests/dagmc/test_convert_to_multigroup.py: DAGMC unit test (a model
  with two fuel volumes sharing one material yields three distinct per-cell
  macroscopics).
• docs/source/usersguide/random_ray.rst: adds cell_wise to the method
  list and to the "Comparison of Automatic MGXS Generation Methods" table.

Verification

• CSG: a 4-shell single-material sphere produces four distinct per-cell cross
  section sets, while material_wise on the same model produces one (regression
  intact).
• DAGMC: the 5-volume dagmc.h5m model (two fuel volumes sharing one material,
  plus water) yields three distinct per-cell macroscopics; void volumes are
  skipped.

Status

• Based on develop (the name+id library keying from Preserve user material names in convert_to_multigroup and avoid overwriting material with same name bug fix #3984 is merged).
• Possible follow-up: distribcell (per-instance) granularity. This PR does
  per-cell-definition (one cross section set per cell, shared across lattice
  instances).

[jtramm]

This looks great @jon-proximafusion -- thanks so much for adding it in! I think it should be a cheap way of improving fidelity vs. the current material-wise method.

Just one small comment below on adding some extra clarifying discussions to the docs.

Additionally - we currently have end-to-end testing for all the MGXS generation techniques in tests/regression_tests/random_ray_auto_convert/test.py, so you could add the new method to the @parametrize list there to test it as well.

[jtramm]

We might want to add a note clarifying that it is generating unique MGXS data for each cell and not for each cell instance. Basically, it would be nice to alert the user that a cell that shows up in multiple locations of a lattice would have the same MGXS data set for all locations. If this type of discussion ends up being too wordy for the table formatting, perhaps it can be included as regular text elsewhere in the section.

• Resolves intra-material spatial variation that material_wise averages
  away, e.g. a thick shield or a steep flux gradient within a single material
• Captures spatial self shielding between cells filled with the same material

I don't completely agree with, as a cell may still be very large and have a steep gradient within it. A full shield wall may easily just be defined with one cell, in which case, you still are sharing the same MGXS throughout the full wall (even if you had applied a cell-under-voxel overlay to make smaller source regions). You only get an improvement if you had manually broken the shield wall down in your geometry definition into multiple cells that cover different depths of the wall. Basically, we don't want to oversell this method in terms of fidelity.

[shimwell]

thanks @jtramm yes good spot, I have updated the docs as suggested

[jon-proximafusion]

Thanks @jtramm, good points on both. I've pushed a doc-only commit:

• Reworded the fidelity claim so it no longer implies an arbitrary intra-cell gradient is resolved. It now states the gain is between distinct cells sharing a material, and added a cons bullet noting fidelity is bounded by the cell definitions (not the source region mesh), so a single large cell uses one cross section set throughout and a gradient is only resolved if the geometry is split into several cells.
• Added a note after the table clarifying that cell_wise generates one cross section set per cell definition, not per cell instance, so a cell repeated across lattice locations shares a single set.

[jon-proximafusion]

Add a cell_wise MGXS generation method

model.convert_to_multigroup(method="cell_wise", groups=...)

Like material_wise, but gives each cell its own multigroup cross sections, so it
captures the intra-material spatial variation that material_wise averages away
(for example a steel material reused in several cells).

Implementation

Full reuse of the material_wise path. Before generation, the material in every
material-filled cell is cloned (each clone gets a unique id via
Material.clone()). The standard per-material generation then produces and assigns
one cross section set per cell. The only new code is the per-cell cloning step in
convert_to_multigroup plus the dispatch entry (about 20 lines). material_wise
behavior is unchanged.

Works for both CSG and DAGMC. convert_to_multigroup already synchronizes DAGMC
cells before generation, so the per-cell clones become standard DAGMC per-cell
material overrides with no special handling.

Contents

• openmc/model/model.py: the per-cell cloning step and dispatch entry.
• tests/unit_tests/test_model.py: CSG unit test (two cells sharing a material get
  distinct macroscopics).
• tests/unit_tests/dagmc/test_convert_to_multigroup.py: DAGMC unit test (a model
  with two fuel volumes sharing one material yields three distinct per-cell
  macroscopics).
• docs/source/usersguide/random_ray.rst: adds cell_wise to the method
  list and to the "Comparison of Automatic MGXS Generation Methods" table.

Verification

• CSG: a 4-shell single-material sphere produces four distinct per-cell cross
  section sets, while material_wise on the same model produces one (regression
  intact).
• DAGMC: the 5-volume dagmc.h5m model (two fuel volumes sharing one material,
  plus water) yields three distinct per-cell macroscopics; void volumes are
  skipped.

Status

• Based on develop (the name+id library keying from Preserve user material names in convert_to_multigroup and avoid overwriting material with same name bug fix #3984 is merged).
• Possible follow-up: distribcell (per-instance) granularity. This PR does
  per-cell-definition (one cross section set per cell, shared across lattice
  instances).

[jtramm]

This looks great @jon-proximafusion -- thanks so much for adding it in! I think it should be a cheap way of improving fidelity vs. the current material-wise method.

Just one small comment below on adding some extra clarifying discussions to the docs.

Additionally - we currently have end-to-end testing for all the MGXS generation techniques in tests/regression_tests/random_ray_auto_convert/test.py, so you could add the new method to the @parametrize list there to test it as well.

[jtramm]

We might want to add a note clarifying that it is generating unique MGXS data for each cell and not for each cell instance. Basically, it would be nice to alert the user that a cell that shows up in multiple locations of a lattice would have the same MGXS data set for all locations. If this type of discussion ends up being too wordy for the table formatting, perhaps it can be included as regular text elsewhere in the section.

• Resolves intra-material spatial variation that material_wise averages
  away, e.g. a thick shield or a steep flux gradient within a single material
• Captures spatial self shielding between cells filled with the same material

I don't completely agree with, as a cell may still be very large and have a steep gradient within it. A full shield wall may easily just be defined with one cell, in which case, you still are sharing the same MGXS throughout the full wall (even if you had applied a cell-under-voxel overlay to make smaller source regions). You only get an improvement if you had manually broken the shield wall down in your geometry definition into multiple cells that cover different depths of the wall. Basically, we don't want to oversell this method in terms of fidelity.

[shimwell]

thanks @jtramm yes good spot, I have updated the docs as suggested

[jon-proximafusion]

Thanks @jtramm, good points on both. I've pushed a doc-only commit:

• Reworded the fidelity claim so it no longer implies an arbitrary intra-cell gradient is resolved. It now states the gain is between distinct cells sharing a material, and added a cons bullet noting fidelity is bounded by the cell definitions (not the source region mesh), so a single large cell uses one cross section set throughout and a gradient is only resolved if the geometry is split into several cells.
• Added a note after the table clarifying that cell_wise generates one cross section set per cell definition, not per cell instance, so a cell repeated across lattice locations shares a single set.