Metadata-Version: 2.4
Name: sim-plugin-simscale
Version: 0.1.1
Summary: SimScale cloud backend driver for sim-cli, distributed as a plugin
Project-URL: Homepage, https://github.com/svd-ai-lab/sim-plugin-simscale
Project-URL: Repository, https://github.com/svd-ai-lab/sim-plugin-simscale
Project-URL: Issues, https://github.com/svd-ai-lab/sim-plugin-simscale/issues
Project-URL: Changelog, https://github.com/svd-ai-lab/sim-plugin-simscale/blob/main/CHANGELOG.md
Author: svd-ai-lab
License-Expression: Apache-2.0
License-File: LICENSE
License-File: LICENSE-NOTICE.md
Keywords: cfd,cloud,plugin,sim-cli,simscale,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: sim-cli-core>=0.3.4
Provides-Extra: test
Requires-Dist: build>=1.0; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# sim-plugin-simscale

Use Codex, Claude Code, or another AI agent to work with
[SimScale](https://www.simscale.com/) cloud simulations through
[sim-cli](https://github.com/svd-ai-lab/sim-cli).

`sim-plugin-simscale` makes SimScale a cloud backend in sim's cross-solver
runtime. It is not a general replacement for the SimScale API or Workbench.
The first alpha release focuses on safe API access checks, session inspection,
and one guarded smoke recipe.

SimScale access, API keys, and compute credits are not bundled. See
[LICENSE-NOTICE.md](LICENSE-NOTICE.md).

## Current Maturity

This is an initial alpha. It has unit coverage and one real-cloud smoke path
for accounts with SimScale API access and enough credits.

The only built-in recipe in `0.1.x` is:

```yaml
kind: pipe_junction_incompressible_smoke
name: My SimScale smoke run
max_compute_cpu_hours: 0.5
```

The recipe uploads a tiny pipe-junction Parasolid fixture, imports geometry,
creates a water incompressible-flow setup, meshes, solves, and downloads a
probe-point CSV.

## Install

PyPI is the primary channel:

```bash
uv pip install sim-plugin-simscale
```

For an exact release:

```bash
uv pip install "sim-plugin-simscale==0.1.1"
```

For source testing against the current main branch:

```bash
uv pip install "git+https://github.com/svd-ai-lab/sim-plugin-simscale.git@main"
```

## Authentication

Create a SimScale API key in your SimScale account and export it locally:

```bash
export SIMSCALE_API_KEY="..."
```

On PowerShell:

```powershell
$env:SIMSCALE_API_KEY = "..."
```

Optional:

```bash
export SIMSCALE_API_URL="https://api.simscale.com"
```

Never commit API keys. Rotate keys that were pasted into chat or logs.

## Common Workflow

Check API access:

```bash
sim check simscale
```

Start an API-backed session:

```bash
sim connect --solver simscale --ui-mode no_gui
sim inspect session.summary
sim inspect simscale.spaces
```

Run bounded JSON commands:

```bash
sim exec '{"command": "list_projects"}'
sim exec '{"command": "list_results", "project_id": "...", "simulation_id": "...", "run_id": "..."}'
```

Run the smoke recipe:

```bash
sim run --solver simscale recipe.yaml
```

Artifacts are written under `.sim/runs/<run-id>/`:

- `metadata.json`
- `events.json`
- `probe_points.csv`

## Credit Safety

The smoke recipe calls SimScale estimate endpoints before starting meshing or
solving. By default it aborts if either estimate exceeds `0.5` CPU-hours.

You can lower the gate in the recipe:

```yaml
max_compute_cpu_hours: 0.2
```

Successful API calls can still create projects/uploads. Compute credit is only
expected after mesh or simulation run start calls.

## Develop

```bash
git clone https://github.com/svd-ai-lab/sim-plugin-simscale
cd sim-plugin-simscale
uv sync --extra test
uv run pytest -q
uv build
```

Live smoke testing is opt-in:

```bash
SIMSCALE_API_KEY=... SIMSCALE_RUN_INTEGRATION=1 uv run pytest tests/test_live_smoke.py -q
```

## License

Apache-2.0. See [LICENSE](LICENSE) and [LICENSE-NOTICE.md](LICENSE-NOTICE.md).
