Arkane matching method name by calvinp0 · Pull Request #814 · ReactionMechanismGenerator/ARC

calvinp0 · 2026-01-06T12:32:41Z

When ARC hands off to Arkane for thermochemistry, it needs to look up atom energy corrections (AEC), bond additivity corrections (BAC), and frequency scale factors from the RMG-database quantum_corrections/data.py. That file uses RMG's own naming convention — all lowercase, no hyphens, and sometimes year-suffixed variants like b97d32023 alongside b97d3.

Previously, ARC did exact string matching against these entries. If a user wrote CCSD(T)-F12/cc-pVTZ-F12 and the database had ccsd(t)f12/ccpvtzf12, it wouldn't match. Users had to know RMG's internal naming to get corrections applied.

Changes

Level.year attribute
Adds an optional year (4-digit int) to the Level class. Validated on construction, included in str, simple(), as_dict(), and build() for serialization/restart support.
Fuzzy matching engine

_normalize_method: lowercase, strip hyphens → DLPNO-CCSD(T)-F12 becomes dlpnoccsd(t)f12
_normalize_basis: lowercase, strip hyphens and spaces → cc-pVTZ-F12 becomes ccpvtzf12
_split_method_year: extracts trailing 4-digit year → b97d32023 → (b97d3, 2023)
_parse_lot_params: regex-extracts method/basis/software from LevelOfTheory(...) strings
_find_best_level_key_for_sp_level: core matcher — iterates all LevelOfTheory(...) keys in a data.py section, normalizes both sides, and selects by year priority:
- Explicit year → exact match only
- No year specified + no-year entry exists → prefer it
- No year specified + only year-suffixed entries → pick latest
_find_best_across_files: searches multiple data.py locations in priority order
_warn_no_match / _all_available_years: actionable warnings listing what years are available
_extract_section: now supports section_end=None (read to EOF), fixing the freq_dict section which is last in the file

arkane_level_of_theory changes in input.yml

The year is specified on arkane_level_of_theory, the Level object dedicated to Arkane lookups:

  arkane_level_of_theory:
    method: b97d3
    basis: def2tzvp
    year: 2023

Most users won't need year at all — the fuzzy matching handles the common case automatically.

Doc updates
Documents the year key on arkane_level_of_theory, warns against putting year suffixes in level_of_theory, explains the fallback behavior.

Copilot

Pull request overview

This PR adds support for optional 4-digit year suffixes to distinguish method variants in the Arkane database (e.g., b97d3 vs b97d32023). The implementation allows users to omit the year (ARC matches the latest available), specify an explicit year, or receive warnings when a requested year is unavailable.

Key changes:

Added year parameter to the Level class with validation requiring 4-digit integers
Implemented flexible method/basis matching logic with year-aware searching in Arkane database
Enhanced error reporting to list available years when a requested year is not found

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/source/advanced.rst	Documents the new `year` parameter with usage examples
arc/level.py	Adds `year` attribute with 4-digit validation and updates string representations
arc/level_test.py	Adds test for year validation (rejects 2-digit, accepts 4-digit)
arc/statmech/arkane.py	Core implementation: adds normalization functions, year-aware matching logic, and improved error messages; also adds spinMultiplicity to non-SMILES species template and thread limit environment variables
arc/statmech/arkane_test.py	Adds test for year-not-found warning behavior and year in _level_to_str

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

arc/statmech/arkane.py

docs/source/advanced.rst

arc/statmech/arkane.py

arc/statmech/arkane_test.py

arc/level.py

Copilot

Pull request overview

Copilot reviewed 10 out of 11 changed files in this pull request and generated 11 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-22T17:54:04Z

docs/source/advanced.rst

+and are not valid QC methods. Do not include year suffixes in ``level_of_theory``; instead, set
+``arkane_level_of_theory`` with a ``year`` value if you need a specific correction year.


The documentation incorrectly advises users to set year in arkane_level_of_theory, but based on the PR description and implementation, the year parameter should be set directly on sp_level (or other level arguments like freq_level, opt_level). The arkane_level_of_theory is typically derived from sp_level unless explicitly overridden. Users should be advised to set the year parameter on sp_level or other level_of_theory parameters, not on arkane_level_of_theory specifically.

Suggested change

and are not valid QC methods. Do not include year suffixes in ``level_of_theory``; instead, set

``arkane_level_of_theory`` with a ``year`` value if you need a specific correction year.

and are not valid QC methods. Do not include year suffixes in ``level_of_theory``; instead, specify a

``year`` key on ``sp_level`` (and/or other job-specific level dictionaries such as ``opt_level``,

``freq_level``, or ``scan_level``) if you need a specific correction year.

Copilot · 2026-01-22T17:54:05Z

docs/source/examples.rst

+set ``arkane_level_of_theory`` with a ``year`` value instead.
+If ``year`` is omitted, ARC will prefer the no-year Arkane entry for that method/basis; if none exists,
+ARC will fall back to the latest available year in the Arkane database.


The documentation incorrectly advises users to set year in arkane_level_of_theory. Based on the PR implementation and examples shown earlier in the documentation (lines 98-112), the year parameter should be set directly on sp_level or other level parameters (opt_level, freq_level, etc.), not specifically on arkane_level_of_theory. The arkane_level_of_theory is typically auto-derived from sp_level unless explicitly overridden.

Suggested change

set ``arkane_level_of_theory`` with a ``year`` value instead.

If ``year`` is omitted, ARC will prefer the no-year Arkane entry for that method/basis; if none exists,

ARC will fall back to the latest available year in the Arkane database.

set a ``year`` field on the relevant level parameter (e.g., ``sp_level``, ``opt_level``, ``freq_level``,

etc.) rather than on ``level_of_theory`` or ``arkane_level_of_theory``. If ``year`` is omitted, ARC will

prefer the no-year Arkane entry for that method/basis; if none exists, ARC will fall back to the latest

available year in the Arkane database.

Copilot · 2026-01-22T17:54:05Z

arc/statmech/arkane.py

+                    f"available years: {_format_years(years)}. "
+                    f"Specify a year to select a matching entry."
+                )
+            return _level_to_str(sp_level)


Inconsistent behavior when Arkane AEC entry is not found: For composite methods (line 978), the function returns _level_to_str(sp_level) even when no matching entry exists in the database. However, for non-composite methods with freq_scale_factor (line 1005), it returns None. This inconsistency could lead to Arkane attempting to use a level of theory that lacks proper corrections. Both cases should handle missing entries consistently, likely by returning None after logging the warning.

Suggested change

return _level_to_str(sp_level)

# No matching AEC level in Arkane DB for this composite method

return None

@calvinp0, can you take a look at this co-pilot comment?

Copilot · 2026-01-22T17:54:05Z

data/quantum_corrections.py

+# Iodine SOC calculated as a weighted average of the electronic spin splittings of the lowest energy state.
+# The splittings are obtained from Huber, K.P.; Herzberg, G., Molecular Spectra and Molecular Structure. IV.
+# Constants of Diatomic Molecules, Van Nostrand Reinhold Co., 1979
+# Spin orbit correction for F, Si, Cl, Br and B taken form https://cccbdb.nist.gov/elecspin.asp


Spelling error: 'form' should be 'from'

Suggested change

# Spin orbit correction for F, Si, Cl, Br and B taken form https://cccbdb.nist.gov/elecspin.asp

# Spin orbit correction for F, Si, Cl, Br and B taken from https://cccbdb.nist.gov/elecspin.asp

arc/statmech/arkane.py

Copilot · 2026-01-22T17:54:06Z

arc/statmech/arkane.py

+def _available_years_for_level(level: "Level",
+                               file_path: str,
+                               section_start: str,
+                               section_end: str) -> list[Optional[int]]:


Type hint inconsistency: This function uses lowercase list[Optional[int]] for the return type, but the file imports and uses List from typing module elsewhere (see line 9 and line 683). For consistency with the rest of the codebase, use List[Optional[int]] instead of list[Optional[int]].

Copilot · 2026-01-22T17:54:06Z

arc/statmech/arkane.py

+    return sorted(years, key=lambda y: (-1 if y is None else y))
+
+
+def _format_years(years: list[Optional[int]]) -> str:


Type hint inconsistency: This function parameter uses lowercase list[Optional[int]], but the file imports and uses List from typing module elsewhere (see line 9 and line 683). For consistency with the rest of the codebase, use List[Optional[int]] instead of list[Optional[int]].

Suggested change

def _format_years(years: list[Optional[int]]) -> str:

def _format_years(years: List[Optional[int]]) -> str:

Copilot · 2026-01-22T17:54:07Z

arc/statmech/arkane.py

+
+    target_method_norm = _normalize_method(level.method)
+    target_base, method_year = _split_method_year(target_method_norm)
+    target_year = getattr(level, 'year', None) if getattr(level, 'year', None) is not None else method_year


The code allows year suffixes in method names (e.g., 'b97d32023') and extracts them for matching, but the documentation explicitly advises against including year suffixes in method names. Consider adding validation to warn or raise an error if a user provides both a year suffix in the method name AND an explicit year parameter with conflicting values, to prevent user confusion and potential bugs.

Suggested change

target_year = getattr(level, 'year', None) if getattr(level, 'year', None) is not None else method_year

explicit_year = getattr(level, 'year', None)

if explicit_year is not None and method_year is not None and explicit_year != method_year:

raise InputError(

f"Conflicting year specifications for level '{level}': "

f"explicit year={explicit_year}, method suffix year={method_year}. "

"Please remove the year suffix from the method name or update the 'year' attribute to match."

)

target_year = explicit_year if explicit_year is not None else method_year

Copilot · 2026-01-22T17:54:07Z

arc/statmech/arkane.py

+    If multiple entries only differ by year, the one with the *latest* year
+    is chosen (year=0 if no year in that entry).


The docstring description at lines 936-937 is misleading. It states that "the one with the latest year is chosen" but this only applies when the user does NOT specify a year AND no no-year entry exists. When a user specifies a year explicitly via the year parameter, only that exact year will be matched. The docstring should clarify that the latest-year fallback only occurs when no year is specified and no no-year entry exists.

Suggested change

If multiple entries only differ by year, the one with the *latest* year

is chosen (year=0 if no year in that entry).

When a year is explicitly specified in the Level, only entries with that exact

year are matched. If no year is specified and an entry without a year exists,

that entry is used. Only when no year is specified and no no-year entry exists,

if multiple entries differ only by year, the one with the *latest* year is

chosen (treating entries with no year as year=0).

Copilot · 2026-01-22T17:54:07Z

arc/statmech/arkane.py

+    qm_corr_files = _get_qm_corrections_files()
+    if not qm_corr_files:
+        return None


When no quantum corrections files are found (qm_corr_files is empty), the function silently returns None without any warning or error message. Consider adding a logger.warning() to inform users that no quantum corrections database files were found, which would help with debugging configuration issues.

alongd · 2026-02-02T05:41:06Z

@calvinp0, can you please see which of the copilot comments are relevant?

alongd

Thanks! I added a couple of comments, both on the same topic

alongd · 2026-02-13T20:33:23Z

arc/main.py

                                         e.g., 'ZINDO/2', 'DLPNO-MP2-F12/D'
                                         For these cases, use the dictionary-type job-specific level of theory arguments
                                         instead (e.g., ``opt_level``).
+        level_of_theory_year (int or str, optional): An optional 4-digit year suffix to apply to the single-point


I think this should not be an arg of ARC. Instead, ARC has individual Level objects for sp_level, opt_liver, etc., and each one has a year attr as you implemented in the prev commit. I recommend removing this from main

alongd · 2026-02-13T20:37:04Z

docs/source/examples.rst

+for Arkane database matching only and are not valid QC methods. If you need a specific correction year,
+specify either:
+
+- ``level_of_theory_year: 2023`` (applies to the SP side of ``level_of_theory``), or


can we instead only give the year in the Level argument, and then use it just for Arkane and not for the ESS calcs?

arc/statmech/arkane_test.py

codecov · 2026-03-28T16:28:21Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.81%. Comparing base (7a890a8) to head (0db4191).
⚠️ Report is 13 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #814      +/-   ##
==========================================
+ Coverage   58.65%   58.81%   +0.15%     
==========================================
  Files          97       97              
  Lines       29222    29355     +133     
  Branches     7755     7791      +36     
==========================================
+ Hits        17140    17264     +124     
- Misses       9882     9885       +3     
- Partials     2200     2206       +6

Flag	Coverage Δ
functionaltests	`58.81% <ø> (+0.15%)`	⬆️
unittests	`58.81% <ø> (+0.15%)`	⬆️

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

☔ View full report in Codecov by Sentry.
📢 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.

alongd

Thanks, @calvinp0!
Please see some minor comments. There's also one comment from co-pilot that's worth looking at, I responded to it

alongd · 2026-03-28T18:00:09Z

arc/level.py

            )
+        if year is not None:
+            self.year = int(year)
+            if self.year < 1000 or self.year > 9999:


Why limit ARC just up to 9999 AD? :)

alongd · 2026-03-28T18:02:48Z

arc/main.py


        self.level_of_theory = ''  # Reset the level_of_theory argument to avoid conflicts upon restarting ARC.

+    def _warn_year_on_non_arkane_levels(self):


Can you implement this in level.py, and call it here? just so we store level-related-things at one place

alongd · 2026-03-28T18:04:26Z

arc/statmech/arkane.py

+    """
+    if basis is None:
+        return None
+    return basis.replace('-', '').replace(' ', '').lower()


Do we expect to have white spaces in the basis set?
Regardless, can this function be combined with _normalize_method()?

alongd · 2026-03-28T18:08:05Z

docs/source/advanced.rst

+      year: 2023

-THe following are examples for **equivalent** definitions::
+If ``year`` is omitted, ARC will prefer the no-year Arkane entry for that method/basis. If none exists,


Unclear what "If none exists" means. If we don't have an entry without a year and neither an entry with a year? Then what do we fall back to?

I will fix the wording. Although do we not fall back to the quantum corrections file in ARC?

alongd · 2026-03-28T18:10:15Z

docs/source/advanced.rst


+Note: Year suffixes in the method (e.g., ``wb97xd32023``) are meant for Arkane database matching
+and are not valid QC methods. Do not include year suffixes in ``level_of_theory``; instead, specify a
+``year`` key on ``arkane_level_of_theory`` if you need a specific correction year.


Thanks for this clarification to the users. To make it clearer, I suggest instead of if you need a specific correction year. to write explicitly if you need a specific atom or bond energy correction year. [See here for all of Arkane's corrections](https://github.com/ReactionMechanismGenerator/RMG-database/blob/main/input/quantum_corrections/data.py)

calvinp0 · 2026-03-28T21:11:06Z

Thanks, @calvinp0! Please see some minor comments. There's also one comment from co-pilot that's worth looking at, I responded to it

I am not sure which comment you mean. I see Outdated ones and a Fixed one

- Introduced an optional year attribute for differentiating methods. - Implemented validation for the year attribute to ensure it is a 4-digit integer. - Added unit tests for year validation and logging warnings when year is set.

… tests

More fixes - cpu architecture warnings

- Added support for year suffix in LevelOfTheory methods. - Implemented functions to extract and normalize method names with years. - Updated get_arkane_model_chemistry to select the latest year when no year is specified. - Added unit tests for year handling, including cases for missing years and conflicting year specifications.

…n parallel execution

alongd

Thanks!

calvinp0 requested review from JintaoWu98, alongd, Copilot and kfir4444 January 6, 2026 12:32

Copilot started reviewing on behalf of calvinp0 January 6, 2026 12:33 View session

Copilot AI reviewed Jan 6, 2026

View reviewed changes

calvinp0 force-pushed the arkane_match branch 2 times, most recently from 7955fd4 to 67e2cfe Compare January 7, 2026 13:55

calvinp0 force-pushed the arkane_match branch 2 times, most recently from 1926671 to 773ab92 Compare January 22, 2026 11:27

calvinp0 requested review from Lilachn91 and Copilot January 22, 2026 17:47

Copilot started reviewing on behalf of calvinp0 January 22, 2026 17:47 View session

Copilot AI reviewed Jan 22, 2026

View reviewed changes

calvinp0 force-pushed the arkane_match branch 2 times, most recently from aeabe6c to 8dee498 Compare January 25, 2026 11:41

calvinp0 force-pushed the arkane_match branch from 0a127ff to 331c440 Compare February 1, 2026 15:58

calvinp0 force-pushed the arkane_match branch from 331c440 to ac61569 Compare February 4, 2026 19:38

github-actions bot added the Module Functional label Feb 4, 2026

calvinp0 force-pushed the arkane_match branch 3 times, most recently from 43ca9df to 9b3e0fe Compare February 12, 2026 11:23

github-actions bot added the Module: Main label Feb 12, 2026

alongd reviewed Feb 13, 2026

View reviewed changes

calvinp0 force-pushed the arkane_match branch from 99c2d4f to 8844419 Compare March 28, 2026 11:25

github-advanced-security bot found potential problems Mar 28, 2026

View reviewed changes

arc/statmech/arkane_test.py Fixed Show fixed Hide fixed

calvinp0 requested a review from alongd March 28, 2026 11:50

calvinp0 force-pushed the arkane_match branch from 8844419 to f689607 Compare March 28, 2026 14:36

alongd reviewed Mar 28, 2026

View reviewed changes

calvinp0 force-pushed the arkane_match branch from f689607 to 86735ad Compare March 28, 2026 21:18

calvinp0 added 3 commits March 29, 2026 12:18

Add pyproject.toml for build system configuration

882d898

Add warning for year attribute on non-Arkane levels and corresponding…

52d522b

… tests

calvinp0 force-pushed the arkane_match branch from 0ca76f6 to 68555ce Compare March 29, 2026 09:18

calvinp0 requested a review from alongd March 29, 2026 09:19

alongd previously approved these changes Mar 29, 2026

View reviewed changes

calvinp0 dismissed alongd’s stale review via 0db4191 March 29, 2026 11:15

calvinp0 force-pushed the arkane_match branch from 68555ce to 0db4191 Compare March 29, 2026 11:15

calvinp0 added 4 commits March 29, 2026 14:15

Add pjrt_executable.cc to warning types in xTBAdapter - Kfir

a9ef231

More fixes - cpu architecture warnings

Update documentation to clarify year handling in arkane_level_of_theory

00c843e

Refactor project name handling in restart tests to avoid collisions i…

0db4191

…n parallel execution

calvinp0 requested a review from alongd March 29, 2026 11:16

alongd approved these changes Mar 29, 2026

View reviewed changes

calvinp0 merged commit 73d661c into main Mar 29, 2026
8 checks passed

calvinp0 deleted the arkane_match branch March 29, 2026 13:11

		and are not valid QC methods. Do not include year suffixes in ``level_of_theory``; instead, set
		``arkane_level_of_theory`` with a ``year`` value if you need a specific correction year.

	return _level_to_str(sp_level)
	# No matching AEC level in Arkane DB for this composite method
	return None

	# Spin orbit correction for F, Si, Cl, Br and B taken form https://cccbdb.nist.gov/elecspin.asp
	# Spin orbit correction for F, Si, Cl, Br and B taken from https://cccbdb.nist.gov/elecspin.asp

		return sorted(years, key=lambda y: (-1 if y is None else y))


		def _format_years(years: list[Optional[int]]) -> str:

-    target_year = getattr(level, 'year', None) if getattr(level, 'year', None) is not None else method_year
+    explicit_year = getattr(level, 'year', None)
+    if explicit_year is not None and method_year is not None and explicit_year != method_year:
+        raise InputError(
+            f"Conflicting year specifications for level '{level}': "
+            f"explicit year={explicit_year}, method suffix year={method_year}. "
+            "Please remove the year suffix from the method name or update the 'year' attribute to match."
+        )
+    target_year = explicit_year if explicit_year is not None else method_year

		If multiple entries only differ by year, the one with the latest year
		is chosen (year=0 if no year in that entry).

-    If multiple entries only differ by year, the one with the *latest* year
-    is chosen (year=0 if no year in that entry).
+    When a year is explicitly specified in the Level, only entries with that exact
+    year are matched. If no year is specified and an entry without a year exists,
+    that entry is used. Only when no year is specified and no no-year entry exists,
+    if multiple entries differ only by year, the one with the *latest* year is
+    chosen (treating entries with no year as year=0).


		self.level_of_theory = '' # Reset the level_of_theory argument to avoid conflicts upon restarting ARC.

		def _warn_year_on_non_arkane_levels(self):

Conversation

calvinp0 commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

alongd commented Feb 2, 2026

Uh oh!

alongd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codecov bot commented Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

alongd left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

calvinp0 commented Jan 6, 2026 •

edited

Loading

codecov bot commented Mar 28, 2026 •

edited

Loading