Metadata-Version: 2.5
Name: simvue
Version: 2.6.0
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>=8.5.0
Requires-Dist: deepmerge>=3.0.1
Requires-Dist: email-validator>=2.3.0
Requires-Dist: flatdict>=4.1.0
Requires-Dist: geocoder>=1.38.1
Requires-Dist: gitpython>=3.1.62
Requires-Dist: humanfriendly>=10.0
Requires-Dist: msgpack>=1.2.2
Requires-Dist: numpy>=2.2.6
Requires-Dist: pandas>=2.3.3
Requires-Dist: pip>=26.2.1
Requires-Dist: psutil>=7.2.2
Requires-Dist: pydantic-extra-types>=2.11.1
Requires-Dist: pydantic>=2.13.5
Requires-Dist: pyjwt>=2.15.0
Requires-Dist: pytest>=9.1.1
Requires-Dist: python-version>=0.0.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: randomname>=0.2.1
Requires-Dist: requests>=2.34.2
Requires-Dist: semver>=3.1.0
Requires-Dist: tabulate>=0.10.0
Requires-Dist: tenacity>=9.1.4
Requires-Dist: toml>=0.10.2
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: unyt>=3.1.0
Provides-Extra: plot
Requires-Dist: matplotlib<4.0.0,>=3.10.0; extra == 'plot'
Requires-Dist: plotly<8.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.
