Add MultipoleExpansion API for unified Cartesian and spherical multipole evaluation#18
Open
harshjha15335 wants to merge 3 commits into
Open
Conversation
Collaborator
|
@harshjha15335 even if IODATA does not contain dipoles nor quadrupoles I think we should name them as atdipoles and atquadrupoles respectively, to make the distinction with molecular multipoles |
harshjha15335
commented
Jul 6, 2026
Contributor
Author
There was a problem hiding this comment.
@ccastilloo ## Summary
This PR expands the validation suite for Cartesian multipole electrostatics.
Added
- Analytical validation tests for monopole, dipole, and quadrupole potential and field.
- Numerical gradient consistency tests (
E = -∇V) for monopoles, dipoles, and quadrupoles. - Scaling-law validation.
- Dipole symmetry tests.
- Stability and near-singularity tests.
- Superposition tests for total potential and total field.
- Additional input validation and vectorized evaluation coverage.
Current status
The new test suite introduces 80 tests, with:
- ✅ 75 passing
- ❌ 5 failing
The failing tests are:
TestQuadrupoleField::test_analytical_on_axisTestQuadrupoleField::test_analytical_equatorial_planeTestQuadrupoleGradientConsistency::test_field_matches_numerical_gradient_general_pointTestQuadrupoleGradientConsistency::test_field_matches_numerical_gradient_randomizedTestQuadrupoleGradientConsistency::test_field_matches_numerical_gradient_near_singularity
These failures are isolated to the newly added quadrupole validation tests. I would appreciate guidance on the intended quadrupole convention and whether these analytical/gradient tests should be updated to match the project's implementation.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces a new
MultipoleExpansioncontainer class that serves as the foundation for a unified electrostatics API.The long-term goal is to provide a single high-level interface for working with atom-centered multipole expansions, independent of whether the underlying moments are stored in Cartesian or spherical form.
Instead of calling separate functions for each representation, users will eventually be able to construct a
MultipoleExpansionobject and evaluate potentials and electric fields through a consistent API.Current changes
This commit introduces the initial container implementation:
MultipoleExpansionclassfrom_cartesian()constructorfrom_spherical()constructorcartesian/spherical)atcoordsatchargesdipolesquadrupolesNo electrostatic evaluation is implemented in this commit.
Planned follow-up commits
Subsequent commits in this PR will add:
Motivation
The current API exposes separate Cartesian and spherical evaluation functions. Introducing
MultipoleExpansionprovides a unified, object-oriented interface while reusing the existing backend implementations without duplicating mathematical expressions.