VULCAN online chemical kinetics calculations

[ipanagiotou02]

Description

(This is a draft PR; copied comment from Issue #6)
In the branch ip_vulcan, the online calculation has been implemented such that it calls VULCAN at every loop (as of now). It creates a vulcan.csv file at every snapshot corresponding to the .nc file of the same time. For example, if the file 66097_atm.nc is created in the data directory, vulcan_66097.csv is created in the offchem directory. This is still a post-processing approach, but it occurs at every snapshot instead of just at the end.

From my project, I knew that a simulation with orbit.semimajoraxis = 0.0316 and outgas.fO2_shift_IW = -4.0 converges relatively quickly (required 29 minutes), so I used it as an initial test. The results are shown below:

A few issues/remarks to make are the following:

• Time: VULCAN's runtime can range from 10 minutes to more than 1 hour, depending on the number of steps it needs to converge. In most cases, convergence is difficult to achieve, and it takes all 30,000 steps to run. This adds a lot of time for a simulation run (the above case went from 29 minutes to 5.29 hours).

• Memory: due to the above, VULCAN greatly increases the size of the proteus_00.log file (from 650 KB to 22 MB). Additionally, each additional .csv file adds 650 KB, and each additional .pkl file adds 5 MB. The example simulation produced 29 of these files times 2 for each, increasing the total simulation memory by 160 MB. For the all_options case, a run with 6 GB allowed the simulation to run for 63 loops and produce 57 vulcan.csv files/snapshots, but without converging. Here is the result up to the point it ran:

Any feedback that you have is appreciated!

Checklist

• I have followed the contributing guidelines
• My code follows the style guidelines of this project
• I have performed a self-review of my code
• My changes generate no new warnings or errors
• I have checked that the tests still pass on my computer
• I have updated the docs, as appropriate
• I have added tests for these changes, as appropriate
• I have checked that all dependencies have been updated, as required

Relevant people

@timlichtenberg @nichollsh @shami-EEG

[nichollsh]

The tests are failing because the run_chemistry function is returning None rather than the Pandas DataFrame of mixing ratios. See comment below about avoiding test regression for offline chemistry, and adding new test for online chemistry.

Also the code style check is failing, just because of some whitespace discrepancies. Also should be easy to fix.

Are the offline/online/manual chemistry 'modes' described in the documentation anywhere? The docs should also briefly explain these differences and their reasons for other users.

In principle these changes look good. Should be easy to fix, and would then be ready to be merged into main :)

[Copilot]

Pull request overview

This PR implements online chemical kinetics calculations by integrating VULCAN to run at every snapshot during a PROTEUS simulation, rather than only as a post-processing step. This enables tracking of atmospheric chemistry evolution throughout the simulation, though at a significant computational cost.

Changes:

• Added online chemistry mode to run VULCAN at every snapshot alongside offline and manual modes
• Implemented snapshot tracking to avoid redundant VULCAN calculations
• Created timestamped output files for each VULCAN run in online mode

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 18 comments.

File	Description
src/proteus/proteus.py	Added snapshot detection logic and VULCAN invocation at each snapshot in the main simulation loop
src/proteus/atmos_chem/wrapper.py	Extended run_chemistry to handle online, offline, and manual modes with appropriate branching logic
src/proteus/atmos_chem/vulcan.py	Added run_vulcan_online function with timestamped file outputs for per-snapshot chemistry calculations

---

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

[nichollsh]

@ipanagiotou02 thanks for making these changes after my review :)
Please let me know when you'd like this PR to be reviewed again.

[codecov]

Codecov Report

❌ Patch coverage is 89.09091% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.50%. Comparing base (57fbb43) to head (d766606).

Files with missing lines	Patch %	Lines
src/proteus/proteus.py	28.57%	4 Missing and 1 partial ⚠️
src/proteus/atmos_chem/vulcan.py	96.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #596      +/-   ##
==========================================
+ Coverage   60.77%   63.50%   +2.72%     
==========================================
  Files          98       98              
  Lines        9388     9420      +32     
  Branches     1263     1274      +11     
==========================================
+ Hits         5706     5982     +276     
+ Misses       3383     3136     -247     
- Partials      299      302       +3     

Flag	Coverage Δ
unit-tests	49.37% <89.09%> (+2.31%)	⬆️

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.

[ipanagiotou02]

Copilot Feedback

All changes were made on the sub-branch.