refactor(c++): 🎨 implementation into either source or inline files

[robertodr]

Summary

🤖 AI text below 🤖

This pull request primarily refactors and reorganizes the implementation of graph encoding and cross-rank storage logic in the monoprop library. The main changes involve moving inline function implementations from headers to a new .cpp file, improving encapsulation, and cleaning up header dependencies. Additionally, a new utility function is added for parameter validation.

Refactoring and Implementation Reorganization

• Moved inline implementations from MPGraphEncodingStorage.h and MPGraphEncodingTypes.h into a new source file MPGraphEncoding.cpp, replacing inline functions with declarations in the headers. This improves build times and encapsulation of implementation details. [1] [2] [3] [4] [5] [6] [7]
• Updated CMake configuration to compile the new MPGraphEncoding.cpp file as part of the build.

API and Dependency Cleanups

• Removed unnecessary includes and unused code from headers, reducing header bloat and unnecessary dependencies. [1] [2] [3] [4]
• Changed the inclusion of inline implementation files in MonomialPropagator.h to a single .inl file, further reducing header complexity.

New and Improved Utilities

• Added a new function expected_num_params to Validation.cpp and exposed it in Validation.h, providing a utility to determine the expected number of parameters from a mapping vector. [1] [2]
• Removed unused static utility functions from MonomialPropagator that are now provided elsewhere.

These changes improve code organization, maintainability, and build performance by isolating implementation details and reducing header dependencies.

Checklist

• Tests added or updated to cover the changes
• Documentation updated (docstrings, docs/, CONTRIBUTING.md) if needed
• CHANGELOG / release notes updated if applicable

AI/LLM disclosure

• I did not use LLM tooling, or used it only privately for ideation
• I used the following tool to help write this PR description:
• I used the following tool to generate or modify code: GitHub Copilot, Claude Sonnet 4.6 and Claude Opus 4.8

Important

By opening this PR I confirm that I have read CONTRIBUTING.md and I agree to the terms of the Contributor License Agreement.

Warning

If you're contributing on behalf of your employer, contact cla@algorithmiq.fi to arrange a Corporate CLA.

[github-actions]

Docs preview: https://pr-203.monoprop-docs.pages.dev

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.70%. Comparing base (16c3255) to head (0941331).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #203   +/-   ##
=======================================
  Coverage   97.70%   97.70%           
=======================================
  Files          14       14           
  Lines         742      742           
  Branches       98       98           
=======================================
  Hits          725      725           
  Misses         12       12           
  Partials        5        5           

Flag	Coverage Δ
cpp	97.70% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

[robertodr]

Results of running just bench on this branch in comparison to main. No regression that I can see.

Heisenberg

Time

Operation	main	refactor-split-impls
model / hubbard	634.404 ms	650.501 ms
model / pauli	210.296 ms	212.944 ms
random / build_graph	9.231 ms	9.292 ms
random / energy	1.520 ms	1.263 ms
random / gradient	6.759 ms	3.709 ms
random / inplace	8.002 ms	7.873 ms
random / pare	4.028 ms	440.2 us

Memory (peak RSS)

Operation	main	refactor-split-impls
model / hubbard	217.61 MiB	216.55 MiB
model / pauli	159.72 MiB	159.81 MiB
random / build_graph	176.58 MiB	176.78 MiB
random / energy	175.51 MiB	175.71 MiB
random / gradient	181.27 MiB	181.48 MiB
random / inplace	197.15 MiB	197.32 MiB
random / pare	176.03 MiB	176.27 MiB

Schrödinger

Time

Operation	main	refactor-split-impls
random / build_graph	162.400 ms	157.635 ms
random / energy	19.136 ms	20.280 ms
random / gradient	40.633 ms	43.227 ms
random / inplace	111.969 ms	111.535 ms
random / pare	10.478 ms	17.221 ms

Memory (peak RSS)

Operation	main	refactor-split-impls
random / build_graph	23580.09 MiB	26896.44 MiB
random / energy	1919.83 MiB	1921.88 MiB
random / gradient	1953.00 MiB	1955.20 MiB
random / inplace	28983.84 MiB	32985.34 MiB
random / pare	1865.67 MiB	1866.43 MiB

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
73.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud