Metadata-Version: 2.4
Name: simvue
Version: 2.5.4
Summary: Simulation tracking and monitoring
Project-URL: homepage, https://simvue.io
Project-URL: repository, https://github.com/simvue-io/python-api
Project-URL: documentation, https://docs.simvue.io
Author-email: Simvue Development Team <info@simvue.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: alerting,metrics,metrics-gathering,monitoring,tracking
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 :: Microsoft :: Windows
Classifier: Operating System :: Unix
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Requires-Dist: click<9.0.0,>=8.4.1
Requires-Dist: deepmerge<3.0,>=2.0
Requires-Dist: email-validator<3.0.0,>=2.2.0
Requires-Dist: flatdict==4.1.0
Requires-Dist: geocoder<2.0.0,>=1.38.1
Requires-Dist: gitpython<4.0.0,>=3.1.44
Requires-Dist: humanfriendly<11.0,>=10.0
Requires-Dist: msgpack<2.0.0,>=1.1.0
Requires-Dist: numpy<3.0.0,>=2.0.0
Requires-Dist: pandas<3.0.0,>=2.2.3
Requires-Dist: psutil<8.0.0,>=6.1.1
Requires-Dist: pydantic-extra-types<3.0.0,>=2.10.5
Requires-Dist: pydantic<3.0.0,>=2.11
Requires-Dist: pyjwt<3.0.0,>=2.13.0
Requires-Dist: pytest<10.0.0,>=9.0.3
Requires-Dist: pyyaml<7.0.0,>=6.0.2
Requires-Dist: randomname<0.3.0,>=0.2.1
Requires-Dist: requests<3.0.0,>=2.32.3
Requires-Dist: semver<4.0.0,>=3.0.4
Requires-Dist: tabulate<0.11.0,>=0.9.0
Requires-Dist: tenacity<10.0.0,>=9.0.0
Requires-Dist: toml<0.11.0,>=0.10.2
Requires-Dist: typing-extensions<5.0.0,>=4.12.2; python_version < '3.11'
Requires-Dist: unyt<4.0.0,>=3.1.0
Provides-Extra: plot
Requires-Dist: matplotlib<4.0.0,>=3.10.0; extra == 'plot'
Requires-Dist: plotly<7.0.0,>=6.0.0; extra == 'plot'
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-%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-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>


## 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.
