Fix/issue 52 large backbones

[simonmb]

Hey, thanks for openclatura. This PR fixes issue #52 and adds support to backbones of 1000 in size.

Summary by Sourcery

Extend systematic backbone stem support and improve robustness for very long carbon chains and rings up to 1000 atoms.

New Features:

• Generate systematic chain and ring stems for skeletal-atom counts from 31 up to 1000 following IUPAC Blue Book numerical terms.

Bug Fixes:

• Avoid recursion-depth failures when enumerating very long unbranched carbon backbones by using an explicit stack-based DFS.

Enhancements:

• Cache generated stems and expose configurable stem length bounds for re-use across naming and ring-rendering logic.
• Update alkoxy prefix substitution to work with generated stems rather than a fixed legacy stem list.
• Improve ring descriptor parsing to recognize systematic cycle prefixes across the full supported stem-length range.

Build:

• Bump package version to 0.2.0 and refresh stored evaluation result artifacts for PubChem, ZINC22, and QM9 datasets.

Documentation:

• Document systematic backbone stem support up to 1000 skeletal atoms and refresh evaluation results and performance comparisons in README and RERUN.md.

Tests:

• Add regression tests for legacy stems, systematic stem generation, invalid length handling, uniqueness of stems, and naming of linear alkanes from C1 through C1000.

Summary by CodeRabbit

• New Features

  • Added systematic chemical stem generation for chain lengths from 1 through 1,000.
  • Expanded support for naming larger backbone structures across chains and rings.
  • Preserved existing naming results for previously supported structures.

• Documentation

  • Updated naming guidance and citation formatting.

• Bug Fixes

  • Improved handling of complex structures and large chain lengths without recursion-related limitations.

• Evaluation

  • Refreshed benchmark results, with improved reported matching accuracy across PubChem and ZINC22 datasets.

[sourcery-ai]

🧙 Sourcery is reviewing your pull request!

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

We encountered an error and are unable to review this PR. We have been notified and are working to fix it.

You can try again by commenting this pull request with @sourcery-ai review, or contact us for help.

[coderabbitai]

Warning

Review limit reached

@simonmb, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 29 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2d43be2e-be5a-433c-a7fe-5adead35a73d

📥 Commits

Reviewing files that changed from the base of the PR and between db7d1d4 and 0c4c192.

⛔ Files ignored due to path filters (10)

• evaluations/results/pubchem/pubchem_seed17_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/pubchem/pubchem_seed42_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/pubchem/pubchem_seed5_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/pubchem/pubchem_seed63_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/pubchem/pubchem_seed87_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/zinc22/zinc22_seed17_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/zinc22/zinc22_seed42_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/zinc22/zinc22_seed5_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/zinc22/zinc22_seed63_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv
• evaluations/results/zinc22/zinc22_seed87_100000_openclatura_opsin_failures.csv is excluded by !**/*.csv

📒 Files selected for processing (30)

• .gitignore
• README.md
• evaluations/RERUN.md
• evaluations/results/pubchem/pubchem_seed17_100000_openclatura.jsonl
• evaluations/results/pubchem/pubchem_seed17_100000_openclatura_opsin_summary.json
• evaluations/results/pubchem/pubchem_seed42_100000_openclatura.jsonl
• evaluations/results/pubchem/pubchem_seed42_100000_openclatura_opsin_summary.json
• evaluations/results/pubchem/pubchem_seed5_100000_openclatura.jsonl
• evaluations/results/pubchem/pubchem_seed5_100000_openclatura_opsin_summary.json
• evaluations/results/pubchem/pubchem_seed63_100000_openclatura.jsonl
• evaluations/results/pubchem/pubchem_seed63_100000_openclatura_opsin_summary.json
• evaluations/results/pubchem/pubchem_seed87_100000_openclatura.jsonl
• evaluations/results/pubchem/pubchem_seed87_100000_openclatura_opsin_summary.json
• evaluations/results/qm9/qm9_all_openclatura.jsonl
• evaluations/results/zinc22/zinc22_seed17_100000_openclatura.jsonl
• evaluations/results/zinc22/zinc22_seed17_100000_openclatura_opsin_summary.json
• evaluations/results/zinc22/zinc22_seed42_100000_openclatura.jsonl
• evaluations/results/zinc22/zinc22_seed42_100000_openclatura_opsin_summary.json
• evaluations/results/zinc22/zinc22_seed5_100000_openclatura.jsonl
• evaluations/results/zinc22/zinc22_seed5_100000_openclatura_opsin_summary.json
• evaluations/results/zinc22/zinc22_seed63_100000_openclatura.jsonl
• evaluations/results/zinc22/zinc22_seed63_100000_openclatura_opsin_summary.json
• evaluations/results/zinc22/zinc22_seed87_100000_openclatura.jsonl
• evaluations/results/zinc22/zinc22_seed87_100000_openclatura_opsin_summary.json
• src/openclatura/__init__.py
• src/openclatura/chains.py
• src/openclatura/formatting.py
• src/openclatura/ring_renderer.py
• src/openclatura/rules/stems.py
• src/openclatura/tests/test_stems.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

📝 Walkthrough

Walkthrough

OpenCLATURA now generates systematic chain stems for lengths 1–1000, updates consumers and tests, refreshes generated evaluation outputs and metrics, bumps the version to 0.2.0, and updates documentation and ignore rules.

Changes

Systematic stem generation

Layer / File(s)	Summary
Stem generation and validation src/openclatura/rules/stems.py	Adds algorithmic numerical-term construction, input validation, cached generation, and systematic coverage through length 1000 while retaining predefined stems.
Expanded consumers and regression coverage src/openclatura/chains.py, src/openclatura/formatting.py, src/openclatura/ring_renderer.py, src/openclatura/tests/test_stems.py, src/openclatura/__init__.py	Replaces recursive path enumeration, iterates across generated stem ranges, adds stem and alkane tests, and sets the package version to 0.2.0.
Evaluation outputs evaluations/results/qm9/qm9_all_openclatura.jsonl, evaluations/results/pubchem/*, evaluations/results/zinc22/*	Updates generated IUPAC names and recalculated OPSIN comparison metrics.
Documentation and environment rules README.md, evaluations/RERUN.md, .gitignore	Documents 1–1000 skeletal-atom support, updates evaluation reporting and citation formatting, and ignores .vercel and .env*.

Estimated code review effort: 3 (Moderate) | ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is related to the main change, which adds support for larger backbones.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AdrianM0]

@simonmb thanks a lot for the contribution! for now we are merging to the tests branch if all tests pass, and then we will make a release to main.

[r-fedorov]

Thanks for the contribution, @simonmb! Supporting chains longer than 30 skeletal atoms is important, and the generated-stem implementation works well for the existing forward-lookup API.

At the moment, STEMS serves two roles:

1. It provides a forward mapping from an atom count to a stem through get()
2. It acts as a finite collection used for reverse recognition in the alkoxy formatter and von Baeyer renderer.

The first use fits this PR well: callers that already know the atom count can continue using get() or stem_for(), while stems above 30 are generated internally.

I am less convinced by expanding the reverse-recognition loops from 30 explicit entries to as many as 1,000 generated candidates.

Alkoxy formatting

substituted_alkoxy_prefix() previously iterated over the 30 entries in STEMS.

The PR now iterates downward from 1000 and calls stems.get() for every candidate until it finds a matching terminal alkyl stem. For a common suffix such as ethyl, this means 999 lookups and comparisons. On the first call, it also generates and caches the 970 stems from 31 through 1000.

Could this reverse-recognition logic instead be encapsulated in stems.py? For example:

def terminal_stem(name: str) -> Stem | None:
    ...

or:

def length_for_alkyl_suffix(name: str) -> int | None:
    ...

This could use a lazily constructed reverse index rather than scanning all supported lengths on every call. Returning the matching stem or length would be more useful here than only returning a boolean.

Von Baeyer recognition

Similarly, von_baeyer_cycle_count() needs to convert the numerical prefix before cyclo back into a cycle count.

The PR handles this by testing _basic_cycle_prefix(count) for every count from 1 through 1000. This works, but it makes reverse recognition a linear scan through all possible values.

Could we add a focused reverse-lookup API alongside the generator? For example:

def length_for_basic_prefix(prefix: str) -> int | None:
    ...

It would also be useful to add regression tests for:

• alkoxy formatting with a generated stem above 30
• von Baeyer prefix recognition above 30