Fix multiplicity parity validation

[calvinp0]

This pull request introduces a parity check for spin multiplicity and electron count in ARCSpecies, ensuring that the specified multiplicity is physically possible given the species' composition and charge. It also adds robust testing for this logic and fixes a test case for nitrogen to use the correct multiplicity and Molpro input. Additionally, it improves code clarity by importing NUMBER_BY_SYMBOL where needed.

Validation of multiplicity and electron count:

• Added a check_multiplicity_parity method to ARCSpecies that verifies the parity of the electron count and multiplicity, raising a SpeciesError if they are inconsistent. This method is called during initialization. [1] [2]
• Implemented a get_number_of_electrons method in ARCSpecies to count electrons from the molecule or xyz.

Testing improvements:

• Added test_check_multiplicity_parity to species_test.py to ensure the parity check works and raises errors for impossible combinations.

Bug fixes and test corrections:

• Updated the nitrogen test case in molpro_test.py to use multiplicity=4 (quartet) and adjusted the Molpro input file templates accordingly. [1] [2]

Code clarity:

• Added the missing import of NUMBER_BY_SYMBOL in species.py to support electron counting.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 63.57%. Comparing base (684967b) to head (7ec66ea).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #914      +/-   ##
==========================================
+ Coverage   63.54%   63.57%   +0.03%     
==========================================
  Files         114      114              
  Lines       38363    38391      +28     
  Branches    10033    10041       +8     
==========================================
+ Hits        24377    24407      +30     
  Misses      11066    11066              
+ Partials     2920     2918       -2     

Flag	Coverage Δ
functionaltests	63.57% <ø> (+0.03%)	⬆️
unittests	63.57% <ø> (+0.03%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

arc/species/species.py:1617

• The warning message uses total_electrons as if it were the actual electron count (e.g., “species with 16 electrons and net charge +1 has 15 electrons”), which is internally inconsistent and can confuse users. Consider clarifying that total_electrons is the neutral electron count / atomic-number sum, and that n_electrons is the actual electron count after applying charge.

                f'Impossible multiplicity for species {self.label}: a species with '
                f'{total_electrons} electrons and a net charge of {self.charge} has '
                f'{n_electrons} electrons, which requires an {parity_word} multiplicity, '
                f'but a multiplicity of {self.multiplicity} was requested. '
                f'Valid nearby multiplicities would be {valid}. '

arc/species/species.py:1612

• The PR description says the parity check raises SpeciesError for inconsistent electron-count/multiplicity combinations, but the implementation only logs a warning and continues constructing the species. Please align behavior and documentation: either raise SpeciesError here (and update tests accordingly) or update the PR description/intent to reflect warning-only validation.

        if n_electrons % 2 != (self.multiplicity - 1) % 2:
            lower = self.multiplicity - 1
            valid = [m for m in (lower, self.multiplicity + 1) if m >= 1]
            parity_word = 'odd' if n_electrons % 2 == 0 else 'even'
            logger.warning(

[alongd]

Thanks, @calvinp0 , Added two comments