Metadata-Version: 2.3
Name: simvue
Version: 2.1.0
Summary: Simulation tracking and monitoring
License: Apache v2
Keywords: tracking,monitoring,metrics,alerting,metrics-gathering
Author: Simvue Development Team
Author-email: info@simvue.io
Requires-Python: >=3.10,<3.14
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: Unix
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Provides-Extra: plot
Requires-Dist: click (>=8.1.8,<9.0.0)
Requires-Dist: deepmerge (>=2.0,<3.0)
Requires-Dist: email-validator (>=2.2.0,<3.0.0)
Requires-Dist: flatdict (>=4.0.1,<5.0.0)
Requires-Dist: geocoder (>=1.38.1,<2.0.0)
Requires-Dist: gitpython (>=3.1.44,<4.0.0)
Requires-Dist: humanfriendly (>=10.0,<11.0)
Requires-Dist: matplotlib (>=3.10.0,<4.0.0) ; extra == "plot"
Requires-Dist: msgpack (>=1.1.0,<2.0.0)
Requires-Dist: numpy (>=2.0.0,<3.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: plotly (>=6.0.0,<7.0.0) ; extra == "plot"
Requires-Dist: psutil (>=6.1.1,<7.0.0)
Requires-Dist: pydantic (>=2.10.6,<3.0.0)
Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
Requires-Dist: randomname (>=0.2.1,<0.3.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: semver (>=3.0.4,<4.0.0)
Requires-Dist: tabulate (>=0.9.0,<0.10.0)
Requires-Dist: tenacity (>=9.0.0,<10.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Requires-Dist: typing-extensions (>=4.12.2,<5.0.0) ; python_version < "3.11"
Project-URL: Documentation, https://docs.simvue.io
Project-URL: Homepage, https://simvue.io
Project-URL: Repository, https://github.com/simvue-io/python-api
Description-Content-Type: text/markdown

# Simvue Python client

<br/>

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/simvue-io/.github/refs/heads/main/simvue-white.png" />
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/simvue-io/.github/refs/heads/main/simvue-black.png" />
    <img alt="Simvue" src="https://raw.githubusercontent.com/simvue-io/.github/refs/heads/main/simvue-black.png" width="500">
  </picture>
</p>

<p align="center">
Collect metadata, metrics and artifacts from simulations, processing and AI/ML training tasks running on any platform, in real time.
</p>

<div align="center">
<a href="https://github.com/simvue-io/client/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/github/license/simvue-io/client"/></a>
<img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue">
<a href="https://pypi.org/project/simvue/" target="_blank"><img src="https://img.shields.io/pypi/v/simvue.svg"/></a>
<a href="https://pepy.tech/project/simvue"><img src="https://static.pepy.tech/badge/simvue"/></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
</div>

<h3 align="center">
 <a href="https://simvue.io"><b>Website</b></a>
  •
  <a href="https://docs.simvue.io"><b>Documentation</b></a>
</h3>

## Configuration
The service URL and token can be defined as environment variables:
```sh
export SIMVUE_URL=...
export SIMVUE_TOKEN=...
```
or a file `simvue.toml` can be created containing:
```toml
[server]
url = "..."
token = "..."
```
The exact contents of both of the above options can be obtained directly by clicking the **Create new run** button on the web UI. Note that the environment variables have preference over the config file.

## Usage example
```python
from simvue import Run

...

if __name__ == "__main__":

    ...

    # Using a context manager means that the status will be set to completed automatically,
    # and also means that if the code exits with an exception this will be reported to Simvue
    with Run() as run:

        # Specify a run name, metadata (dict), tags (list), description, folder
        run.init('example-run-name',
                 {'learning_rate': 0.001, 'training_steps': 2000, 'batch_size': 32}, # Metadaata
                 ['tensorflow'],                                                     # Tags
                 'This is a test.',                                                  # Description
                 '/Project-A/part1')                                                 # Folder full path

        # Set folder details if necessary
        run.set_folder_details('/Project-A/part1',                     # Folder full path
                               metadata={},                            # Metadata
                               tags=['tensorflow'],                    # Tags
                               description='This is part 1 of a test') # Description

        # Upload the code
        run.save_file('training.py', 'code')

        # Upload an input file
        run.save_file('params.in', 'input')

        # Add an alert (the alert definition will be created if necessary)
        run.create_metric_threshold_alert(
              name='loss-too-high',   # Name
              rule='is above',        # Rule
              metric='loss',          # Metric
              frequency=1,            # Frequency
              window=1,               # Window
              threshold=10,           # Threshold
              notification='email'   # Notification type
        )

        ...

        while not converged:

            ...

            # Send metrics inside main application loop
            run.log_metrics({'loss': 0.5, 'density': 34.4})

            ...

        # Upload an output file
        run.save_file('output.cdf', 'output')

        # If we weren't using a context manager we'd need to end the run
        # run.close()
```

## License

Released under the terms of the [Apache 2](https://github.com/simvue-io/client/blob/main/LICENSE) license.

