Add derivative tally based k_eff search support for material perturbations

[pranavkantgaur]

Description

This PR extends the recently added Model.keff_search method for material input parameters by leveraging derivative tallies. It adds least-squares curve fitting over a combination of K_eff evaluations and its derivatives as an alternative method to GRSecant's curve fitting. We have observed considerable reduction in the required number of MC evaluations for some cases (reproducible using test_tally_deriv_keff_search.py in the attached zip). Results are consistent with the primary work by @smharper as reported here.

It is an initial work on #980 and is related to: #3569, #2693.

Results from the attached demo script are as:

TABLE 1: BORON CONCENTRATION SEARCH RESULTS

Method	Final Sol (ppm)	MC Runs	Tot Batches	Time (s)	Converged
GRsecant (no deriv)	20.4	17	2282	55.48	True
Least Squares (with deriv)	30.0	9	1090	31.20	True

Efficiency Gains (relative to GRsecant baseline)

Least Squares (with deriv):

• MC runs: +47.1% (9 vs 17)
• Total batches: +52.2% (1090 vs 2282)
• Elapsed time: +43.8% (31.20s vs 55.48s)

---

TABLE 2: FUEL DENSITY SEARCH RESULTS

Method	Final Density (g/cm³)	MC Runs	Tot Batches	Time (s)	Converged
GRsecant (no deriv)	7.007	43	9627	228.95	True
Least Squares (with deriv)	6.978	27	4783	137.50	True

Efficiency Gains (relative to GRsecant baseline)

Least Squares (with deriv):

• MC runs: +37.2% (27 vs 43)
• Total batches: +50.3% (4783 vs 9627)
• Elapsed time: +39.9% (137.50s vs 228.95s)

Checklist

• I have performed a self-review of my own code
• I have run clang-format (version 15) on any C++ source files (if applicable)
• I have followed the style guidelines for Python source files (if applicable)
• I have made corresponding changes to the documentation (if applicable)
• I have added tests that prove my fix is effective or that my feature works (if applicable)

[GuySten]

This looks like a nice feature.
A better place for the examples should be in the openmc-notebooks repo though.

[mvineetmenon]

@GuySten

Thanks for the suggestion! This PR introduces a new feature enhancement to OpenMC by extending Model.keff_search to support material perturbations using derivative tallies (with least-squares fitting, uncertainty weighting, etc.).

Since this is a new capability being added in this PR, any accompanying notebook demonstrations may go to the separate openmc-notebooks repository rather than being included here. The notebooks in openmc-notebooks are intended as demonstrations and tutorials for existing features of released versions of OpenMC, not for showcasing in-development changes.

Once this PR is merged and the feature lands in a release, we can open a PR there to add a notebook example! That would be a great way to highlight the new functionality.

[GuySten]

I thinks that the examples folder in openmc has alot less visibility than the openmc-notebooks repository. You've clearly put alot of work in the examples in this PR and I think it will be better to put them in a place that is more visible to users.
I personally also like examples in the format of jupyter notebooks so you can more easily test the new feature.

What I meant was lets remove the example files in this PR and merge it without them.
And once it is merged you should open a PR in openmc-notebooks with the example files converted into notebooks.
That way more users will be exposed to this feature.

You can also add the examples to the description of this PR so people can run it while it still in development, if you want.

[pranavkantgaur]

I thinks that the examples folder in openmc has alot less visibility than the openmc-notebooks repository. You've clearly put alot of work in the examples in this PR and I think it will be better to put them in a place that is more visible to users. I personally also like examples in the format of jupyter notebooks so you can more easily test the new feature.

What I meant was lets remove the example files in this PR and merge it without them. And once it is merged you should open a PR in openmc-notebooks with the example files converted into notebooks. That way more users will be exposed to this feature.

You can also add the examples to the description of this PR so people can run it while it still in development, if you want.

Sure, I will take out the examples from this PR and add them as demo scripts in the description. Later maybe update the existing PR in openmc-notebooks with this example.

[GuySten]

Looks good.

@pranavkantgaur, If you agree with my changes I will merge tomorrow.

[pranavkantgaur]

Looks good.

@pranavkantgaur, If you agree with my changes I will merge tomorrow.

@GuySten Changes look good, thanks. There was a minor change to handle undefined variable reference for nuclide-density derivatives, I have added that. Also, I have updated the note in the docstrings to not to use this method (yet) for the temperature derivatives.

Besides this, MR description is updated with results from the attached demo script.

[paulromano]

Thanks for the PR @pranavkantgaur and the review @GuySten. I'd like to review this before we merge so I'm putting a placeholder review for now.