Create operational timer: stopwatch

[Oakley Brunt (oakleybrunt)]

PR Summary

Sci/Tech Reviewer: Sara Cusworth (@mo-saracusworth)
Code Reviewer: Steve Mullerworth (@stevemullerworth)

Linked with MetOffice/lfric_apps#652, this PR adds the infrastructure for an operational timer. The implementation is based on Andrew Coughtrie (@andrewcoughtrie)'s suggestions (created with AI assistance), though I have added the ability to pause and resume the timer.

The timer will be called stopwatch since it is used in a similar vein to a lap timer.

Code Quality Checklist

• I have performed a self-review of my own code
• My code follows the project's style guidelines
• Comments have been included that aid understanding and enhance the readability of the code
• My changes generate no new warnings
• All automated checks in the CI pipeline have completed successfully

Testing

• I have tested this change locally, using the LFRic Core rose-stem suite
• If required (e.g. API changes) I have also run the LFRic Apps test suite using this branch
• If any tests fail (rose-stem or CI) the reason is understood and acceptable (e.g. kgo changes)
• I have added tests to cover new functionality as appropriate (e.g. system tests, unit tests, etc.)
• Any new tests have been assigned an appropriate amount of compute resource and have been allocated to an appropriate testing group (i.e. the developer tests are for jobs which use a small amount of compute resource and complete in a matter of minutes)

trac.log

Test Suite Results - lfric_core - stopwatch_core/run1

Suite Information

Item	Value
Suite Name	stopwatch_core/run1
Suite User	oakley.brunt
Workflow Start	2026-09-10T12:27:28
Groups Run	developer

Dependency	Reference	Main Like
lfric_core	oakleybrunt/lfric_core@operational-timer	False
SimSys_Scripts	MetOffice/SimSys_Scripts@cab3315	True

Task Information

✅ succeeded tasks - 433

Security Considerations

• I have reviewed my changes for potential security issues
• Sensitive data is properly handled (if applicable)
• Authentication and authorisation are properly implemented (if applicable)

Performance Impact

• Performance of the code has been considered and, if applicable, suitable performance measurements have been conducted

AI Assistance and Attribution

• Some of the content of this change has been produced with the assistance of Generative AI tool name (e.g., Met Office Github Copilot Enterprise, Github Copilot Personal, ChatGPT GPT-4, etc) and I have followed the Simulation Systems AI policy (including attribution labels)

The original implementation suggested by Andrew Coughtrie (@andrewcoughtrie) was created with the assistance of AI tools.

Documentation

• Where appropriate I have updated documentation related to this change and confirmed that it builds correctly

PSyclone Approval

• If you have edited any PSyclone-related code (e.g. PSyKAl-lite, Kernel interface, optimisation scripts, LFRic data structure code) then please contact the HPC Optimisation Team

Sci/Tech Review

• I understand this area of code and the changes being added
• The proposed changes correspond to the pull request description
• Documentation is sufficient (do documentation papers need updating)
• Sufficient testing has been completed

(Please alert the code reviewer via a tag when you have approved the SR)

Code Review

• All dependencies have been resolved
• Related Issues have been properly linked and addressed
• CLA compliance has been confirmed
• Code quality standards have been met
• Tests are adequate and have passed
• Documentation is complete and accurate
• Security considerations have been addressed
• Performance impact is acceptable

[Steve Mullerworth (stevemullerworth)]

I'm tagged as code owner reviewer. I note that the description references use of AI which means that the code should include a comment indicating that Enterprise AI was used (I assume it was) and what model was used.
The requirement comes from operations, but it looks like a generic tool, so maybe the procedure names and file name could be more generic.
Please can API documentation be added to an appropriate section of the Sphinx docs (though I suspect the "official" timer documentation may not have been written with which this approach can be contrasted...).

[Oakley Brunt (oakleybrunt)]

so maybe the procedure names and file name could be more generic.

Did you have anything in mind for the file and type name?
Suggestions:

• mini_timer_type (smaller than timer_mod)
• tmp_timer_type (temporary lifetime, not for a whole run)
• timer_lite_type or lite_timer_type

For the procedures, I have dropped the _timer so now they are start, stop, pause, resume.

[Andrew Coughtrie (andrewcoughtrie)]

so maybe the procedure names and file name could be more generic.

Did you have anything in mind for the file and type name? Suggestions:

• mini_timer_type (smaller than timer_mod)
• tmp_timer_type (temporary lifetime, not for a whole run)
• timer_lite_type or lite_timer_type

For the procedures, I have dropped the _timer so now they are start, stop, pause, resume.

I would be slightly concerned that making the name and implied usage too generic would result in people using it when they should be using timing_mod. I would consider this tool to be for permanent timers and should only appear sparsely throughout the code.

[Oakley Brunt (oakleybrunt)]

I would consider this tool to be for permanent timers

permatime_type?

[Oakley Brunt (oakleybrunt)]

Steve Mullerworth (@stevemullerworth), Andrew Coughtrie (@andrewcoughtrie) can we decide the naming today please - I'd like to get this wrapped up.

[Steve Mullerworth (stevemullerworth)]

Following up from my comment above, I like stopwatch! Some documentation would still be good!

Also, the year number in the copyright statement is no longer required.

[Oakley Brunt (oakleybrunt)]

Sara Cusworth (@mo-saracusworth) this is ready for review when you have time :)