Adding regularization objective option to parmest

[sscini]

Fixes # .

Summary/Motivation:

Currently, the only default objective is the standard SSE objective. This edit provides the capability to add a
regularization term to the SSE objective with a prior FIM and reference parameter values.

Changes proposed in this PR:

• Added prior_FIM and theta_ref as keyword arguments for Estimator
• Added options within Estimator to apply the regularization term to SSE if the new arguments were defined

TODO before converting from draft

• Receive feedback from collaborators on logical setup
• Finish edits and debug
• Confirm functionality with examples

Legal Acknowledgement

By contributing to this software project, I have read the contribution guide and agree to the following terms and conditions for my contribution:

1. I agree my contributions are submitted under the BSD license.
2. I represent I am authorized to make the contributions and grant the license. If my employer has rights to intellectual property that includes these contributions, I represent that I have received permission to make contributions and grant the required license on behalf of that employer.

[sscini]

@djlaky @adowling2 Please provide early feedback

[adowling2]

@sscini See my early feedback.

[adowling2]

Does this run? My intuition is that you need to write out the matrix multiplication and cannot use matrix multiplication.

[sscini]

UPDATE (07/15/25); Intended to be added AFTER Shammah's weighted SSE PR (#3535) and follow a similar format, adding another option for available objectives using Enums.

Currently preparing for next stage of review

[sscini]

@adowling2 @djlaky Made some edits to this finally. Meant to follow Shammah's layout in PR #3535, waiting to merge, currently some conflicts I cannot resolve on my end.

Made it's own full objective instead of a term to add. Also added weighting term.

Ready for next round of review.

[sscini]

Will not be actively worked on before finalization of _Q_opt_blocks. Closing for now to resume in the future.

[sscini]

Got L2 regularization working, still need to modify to improve implementation slightly. Made prior_FIM and theta_ref as pd.DataFrames because this is how parmest would return them, and would not be reliant on assuming order is correct.

[sscini]

Made theta_ref a pd.Series so if you take theta and invert the covariance outputs from theta_est(), you can feed them directly back in.

[sscini]

@adowling2 L2 functionality working. Made theta_ref a pd.Series and prior_FIM a pd.DataFrame so parmest outputs can be used as inputs. All previous tests passing. Added preliminary toy example using rooney_biegler to show movement of estimated theta and reduction of covariance. Please review when available.