Add trace decorator for "lazy" monitoring of functions

[kzscisoft]

trace decorator for quick function monitoring

Issue: #664

Python Version(s) Tested: 3.13

Operating System(s): Windows 11

Documentation PR: Issue on Docs repo.

📝 Summary

A decorator which allows the user to lazily track the variables within the function:

• User can exclude variables using exclude=["glob_expr*"].
• User can include variables using include=["glob_expr*"].
• Variables prefixed with _ are ignored.
• Use can attach an empty dictionary into which the decorator will pass session information.

import simvue.simlab as sv_lab
import time

@sv_lab.trace(include=["monitor_*"])
def run_simulation():
    monitor_x = 0
    monitor_y = 0

    for i in range(10):
         time.sleep(1)
         monitor_x = i
         monitor_y = monitor_x ** 2

🔄 Changes

Added new simlab sub-module, name pending review, the lab is either a user sandboxing module, or a place where new features are initially placed before becoming part of the main framework.

✔️ Checklist

• Unit and integration tests passing.
• Pre-commit hooks passing.
• Quality checks passing.
• Updated the documentation.