Skip to content

Add MultipoleExpansion API for unified Cartesian and spherical multipole evaluation#18

Open
harshjha15335 wants to merge 3 commits into
theochem:mainfrom
harshjha15335:feature/spherical-potential-pr
Open

Add MultipoleExpansion API for unified Cartesian and spherical multipole evaluation#18
harshjha15335 wants to merge 3 commits into
theochem:mainfrom
harshjha15335:feature/spherical-potential-pr

Conversation

@harshjha15335

Copy link
Copy Markdown
Contributor

Summary

This PR introduces a new MultipoleExpansion container 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 MultipoleExpansion object and evaluate potentials and electric fields through a consistent API.

Current changes

This commit introduces the initial container implementation:

  • Add new MultipoleExpansion class
  • Add from_cartesian() constructor
  • Add from_spherical() constructor
  • Store representation metadata (cartesian / spherical)
  • Store atom-centered multipole data using IOData naming conventions
    • atcoords
    • atcharges
    • dipoles
    • quadrupoles
  • Add lightweight validation
  • Add type hints
  • Add Sphinx-compatible documentation

No electrostatic evaluation is implemented in this commit.

Planned follow-up commits

Subsequent commits in this PR will add:

  • dispatch to Cartesian electrostatic routines
  • dispatch to spherical electrostatic routines
  • comprehensive validation
  • unit tests
  • verification that Cartesian and spherical representations produce identical results

Motivation

The current API exposes separate Cartesian and spherical evaluation functions. Introducing MultipoleExpansion provides a unified, object-oriented interface while reusing the existing backend implementations without duplicating mathematical expressions.

@ccastilloo

Copy link
Copy Markdown
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

Comment thread tests/test_multipole.py

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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_axis
  • TestQuadrupoleField::test_analytical_equatorial_plane
  • TestQuadrupoleGradientConsistency::test_field_matches_numerical_gradient_general_point
  • TestQuadrupoleGradientConsistency::test_field_matches_numerical_gradient_randomized
  • TestQuadrupoleGradientConsistency::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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants