# {py:mod}`simvx.core.testing.benchmark`

```{py:module} simvx.core.testing.benchmark
```

```{autodoc2-docstring} simvx.core.testing.benchmark
:allowtitles:
```

## Module Contents

### Classes

````{list-table}
:class: autosummary longtable
:align: left

* - {py:obj}`BenchmarkResult <simvx.core.testing.benchmark.BenchmarkResult>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult
    :summary:
    ```
* - {py:obj}`MachineInfo <simvx.core.testing.benchmark.MachineInfo>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo
    :summary:
    ```
* - {py:obj}`PerfRecord <simvx.core.testing.benchmark.PerfRecord>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord
    :summary:
    ```
* - {py:obj}`HistoryStore <simvx.core.testing.benchmark.HistoryStore>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.HistoryStore
    :summary:
    ```
* - {py:obj}`PerfRecorder <simvx.core.testing.benchmark.PerfRecorder>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecorder
    :summary:
    ```
````

### Functions

````{list-table}
:class: autosummary longtable
:align: left

* - {py:obj}`bench_scene_runner <simvx.core.testing.benchmark.bench_scene_runner>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.bench_scene_runner
    :summary:
    ```
* - {py:obj}`bench_headless_render <simvx.core.testing.benchmark.bench_headless_render>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.bench_headless_render
    :summary:
    ```
* - {py:obj}`perf_dir <simvx.core.testing.benchmark.perf_dir>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.perf_dir
    :summary:
    ```
* - {py:obj}`record_key <simvx.core.testing.benchmark.record_key>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.record_key
    :summary:
    ```
* - {py:obj}`compare <simvx.core.testing.benchmark.compare>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.compare
    :summary:
    ```
* - {py:obj}`make_perf_recorder <simvx.core.testing.benchmark.make_perf_recorder>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.make_perf_recorder
    :summary:
    ```
* - {py:obj}`perf_pytest_addoption <simvx.core.testing.benchmark.perf_pytest_addoption>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.perf_pytest_addoption
    :summary:
    ```
````

### Data

````{list-table}
:class: autosummary longtable
:align: left

* - {py:obj}`__all__ <simvx.core.testing.benchmark.__all__>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.__all__
    :summary:
    ```
* - {py:obj}`DEFAULT_TOLERANCE <simvx.core.testing.benchmark.DEFAULT_TOLERANCE>`
  - ```{autodoc2-docstring} simvx.core.testing.benchmark.DEFAULT_TOLERANCE
    :summary:
    ```
````

### API

````{py:data} __all__
:canonical: simvx.core.testing.benchmark.__all__
:value: >
   ['BenchmarkResult', 'HistoryStore', 'MachineInfo', 'PerfRecord', 'PerfRecorder', 'bench_headless_ren...

```{autodoc2-docstring} simvx.core.testing.benchmark.__all__
```

````

````{py:data} DEFAULT_TOLERANCE
:canonical: simvx.core.testing.benchmark.DEFAULT_TOLERANCE
:value: >
   0.2

```{autodoc2-docstring} simvx.core.testing.benchmark.DEFAULT_TOLERANCE
```

````

`````{py:class} BenchmarkResult
:canonical: simvx.core.testing.benchmark.BenchmarkResult

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult
```

````{py:attribute} name
:canonical: simvx.core.testing.benchmark.BenchmarkResult.name
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.name
```

````

````{py:attribute} count
:canonical: simvx.core.testing.benchmark.BenchmarkResult.count
:type: int
:value: >
   0

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.count
```

````

````{py:attribute} total_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.total_ms
:type: float
:value: >
   0.0

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.total_ms
```

````

````{py:attribute} frames
:canonical: simvx.core.testing.benchmark.BenchmarkResult.frames
:type: int
:value: >
   0

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.frames
```

````

````{py:attribute} samples_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.samples_ms
:type: list[float]
:value: >
   'field(...)'

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.samples_ms
```

````

````{py:attribute} gpu_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.gpu_ms
:type: float | None
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.gpu_ms
```

````

````{py:attribute} backend
:canonical: simvx.core.testing.benchmark.BenchmarkResult.backend
:type: str
:value: >
   'default'

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.backend
```

````

````{py:attribute} metric
:canonical: simvx.core.testing.benchmark.BenchmarkResult.metric
:type: str
:value: >
   'frame_ms'

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.metric
```

````

````{py:attribute} value
:canonical: simvx.core.testing.benchmark.BenchmarkResult.value
:type: float | None
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.value
```

````

````{py:attribute} lower_is_better
:canonical: simvx.core.testing.benchmark.BenchmarkResult.lower_is_better
:type: bool
:value: >
   True

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.lower_is_better
```

````

````{py:attribute} extra
:canonical: simvx.core.testing.benchmark.BenchmarkResult.extra
:type: dict[str, float]
:value: >
   'field(...)'

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.extra
```

````

````{py:property} avg_frame_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.avg_frame_ms
:type: float

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.avg_frame_ms
```

````

````{py:property} fps
:canonical: simvx.core.testing.benchmark.BenchmarkResult.fps
:type: float

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.fps
```

````

````{py:property} per_object_us
:canonical: simvx.core.testing.benchmark.BenchmarkResult.per_object_us
:type: float

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.per_object_us
```

````

````{py:property} p50_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.p50_ms
:type: float

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.p50_ms
```

````

````{py:property} p95_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.p95_ms
:type: float

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.p95_ms
```

````

````{py:property} p99_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.p99_ms
:type: float

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.p99_ms
```

````

````{py:property} min_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.min_ms
:type: float

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.min_ms
```

````

````{py:property} max_ms
:canonical: simvx.core.testing.benchmark.BenchmarkResult.max_ms
:type: float

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.max_ms
```

````

````{py:method} metric_value() -> float
:canonical: simvx.core.testing.benchmark.BenchmarkResult.metric_value

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.metric_value
```

````

````{py:method} report() -> str
:canonical: simvx.core.testing.benchmark.BenchmarkResult.report

```{autodoc2-docstring} simvx.core.testing.benchmark.BenchmarkResult.report
```

````

`````

````{py:function} bench_scene_runner(root, frames: int = 120, draw: bool = False, *, backend: str = 'default') -> simvx.core.testing.benchmark.BenchmarkResult
:canonical: simvx.core.testing.benchmark.bench_scene_runner

```{autodoc2-docstring} simvx.core.testing.benchmark.bench_scene_runner
```
````

````{py:function} bench_headless_render(scene_or_cls, frames: int = 60, width: int = 1280, height: int = 720, *, warmup: int = 0, telemetry_keys: tuple[str, ...] = (), backend: str = 'default', **kwargs) -> simvx.core.testing.benchmark.BenchmarkResult
:canonical: simvx.core.testing.benchmark.bench_headless_render

```{autodoc2-docstring} simvx.core.testing.benchmark.bench_headless_render
```
````

`````{py:class} MachineInfo
:canonical: simvx.core.testing.benchmark.MachineInfo

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo
```

````{py:attribute} host
:canonical: simvx.core.testing.benchmark.MachineInfo.host
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.host
```

````

````{py:attribute} os
:canonical: simvx.core.testing.benchmark.MachineInfo.os
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.os
```

````

````{py:attribute} cpu
:canonical: simvx.core.testing.benchmark.MachineInfo.cpu
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.cpu
```

````

````{py:attribute} cpu_count
:canonical: simvx.core.testing.benchmark.MachineInfo.cpu_count
:type: int
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.cpu_count
```

````

````{py:attribute} ram_gb
:canonical: simvx.core.testing.benchmark.MachineInfo.ram_gb
:type: float
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.ram_gb
```

````

````{py:attribute} python
:canonical: simvx.core.testing.benchmark.MachineInfo.python
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.python
```

````

````{py:attribute} free_threaded
:canonical: simvx.core.testing.benchmark.MachineInfo.free_threaded
:type: bool
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.free_threaded
```

````

````{py:attribute} gpu
:canonical: simvx.core.testing.benchmark.MachineInfo.gpu
:type: str
:value: >
   'unknown'

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.gpu
```

````

````{py:attribute} git_commit
:canonical: simvx.core.testing.benchmark.MachineInfo.git_commit
:type: str
:value: >
   'unknown'

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.git_commit
```

````

````{py:method} capture() -> simvx.core.testing.benchmark.MachineInfo
:canonical: simvx.core.testing.benchmark.MachineInfo.capture
:classmethod:

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.capture
```

````

````{py:method} to_dict() -> dict[str, typing.Any]
:canonical: simvx.core.testing.benchmark.MachineInfo.to_dict

```{autodoc2-docstring} simvx.core.testing.benchmark.MachineInfo.to_dict
```

````

`````

````{py:function} perf_dir() -> pathlib.Path
:canonical: simvx.core.testing.benchmark.perf_dir

```{autodoc2-docstring} simvx.core.testing.benchmark.perf_dir
```
````

````{py:function} record_key(suite: str, name: str, backend: str, count: int, metric: str) -> str
:canonical: simvx.core.testing.benchmark.record_key

```{autodoc2-docstring} simvx.core.testing.benchmark.record_key
```
````

`````{py:class} PerfRecord
:canonical: simvx.core.testing.benchmark.PerfRecord

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord
```

````{py:attribute} ts
:canonical: simvx.core.testing.benchmark.PerfRecord.ts
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.ts
```

````

````{py:attribute} suite
:canonical: simvx.core.testing.benchmark.PerfRecord.suite
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.suite
```

````

````{py:attribute} name
:canonical: simvx.core.testing.benchmark.PerfRecord.name
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.name
```

````

````{py:attribute} backend
:canonical: simvx.core.testing.benchmark.PerfRecord.backend
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.backend
```

````

````{py:attribute} count
:canonical: simvx.core.testing.benchmark.PerfRecord.count
:type: int
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.count
```

````

````{py:attribute} metric
:canonical: simvx.core.testing.benchmark.PerfRecord.metric
:type: str
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.metric
```

````

````{py:attribute} value
:canonical: simvx.core.testing.benchmark.PerfRecord.value
:type: float
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.value
```

````

````{py:attribute} lower_is_better
:canonical: simvx.core.testing.benchmark.PerfRecord.lower_is_better
:type: bool
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.lower_is_better
```

````

````{py:attribute} avg_frame_ms
:canonical: simvx.core.testing.benchmark.PerfRecord.avg_frame_ms
:type: float
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.avg_frame_ms
```

````

````{py:attribute} fps
:canonical: simvx.core.testing.benchmark.PerfRecord.fps
:type: float
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.fps
```

````

````{py:attribute} p95_ms
:canonical: simvx.core.testing.benchmark.PerfRecord.p95_ms
:type: float
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.p95_ms
```

````

````{py:attribute} p99_ms
:canonical: simvx.core.testing.benchmark.PerfRecord.p99_ms
:type: float
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.p99_ms
```

````

````{py:attribute} gpu_ms
:canonical: simvx.core.testing.benchmark.PerfRecord.gpu_ms
:type: float | None
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.gpu_ms
```

````

````{py:attribute} extra
:canonical: simvx.core.testing.benchmark.PerfRecord.extra
:type: dict[str, float]
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.extra
```

````

````{py:attribute} machine
:canonical: simvx.core.testing.benchmark.PerfRecord.machine
:type: dict[str, typing.Any]
:value: >
   None

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.machine
```

````

````{py:property} key
:canonical: simvx.core.testing.benchmark.PerfRecord.key
:type: str

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.key
```

````

````{py:method} from_result(suite: str, result: simvx.core.testing.benchmark.BenchmarkResult, machine: simvx.core.testing.benchmark.MachineInfo) -> simvx.core.testing.benchmark.PerfRecord
:canonical: simvx.core.testing.benchmark.PerfRecord.from_result
:classmethod:

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.from_result
```

````

````{py:method} to_dict() -> dict[str, typing.Any]
:canonical: simvx.core.testing.benchmark.PerfRecord.to_dict

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecord.to_dict
```

````

`````

`````{py:class} HistoryStore(root: pathlib.Path | None = None, machine: simvx.core.testing.benchmark.MachineInfo | None = None)
:canonical: simvx.core.testing.benchmark.HistoryStore

```{autodoc2-docstring} simvx.core.testing.benchmark.HistoryStore
```

```{rubric} Initialization
```

```{autodoc2-docstring} simvx.core.testing.benchmark.HistoryStore.__init__
```

````{py:method} append(record: simvx.core.testing.benchmark.PerfRecord) -> None
:canonical: simvx.core.testing.benchmark.HistoryStore.append

```{autodoc2-docstring} simvx.core.testing.benchmark.HistoryStore.append
```

````

````{py:method} baselines() -> dict[str, dict[str, typing.Any]]
:canonical: simvx.core.testing.benchmark.HistoryStore.baselines

```{autodoc2-docstring} simvx.core.testing.benchmark.HistoryStore.baselines
```

````

````{py:method} baseline(key: str) -> dict[str, typing.Any] | None
:canonical: simvx.core.testing.benchmark.HistoryStore.baseline

```{autodoc2-docstring} simvx.core.testing.benchmark.HistoryStore.baseline
```

````

````{py:method} update_baselines(records: dict[str, dict[str, typing.Any]]) -> None
:canonical: simvx.core.testing.benchmark.HistoryStore.update_baselines

```{autodoc2-docstring} simvx.core.testing.benchmark.HistoryStore.update_baselines
```

````

`````

````{py:function} compare(current: float, baseline: float, lower_is_better: bool, tol: float = DEFAULT_TOLERANCE) -> str
:canonical: simvx.core.testing.benchmark.compare

```{autodoc2-docstring} simvx.core.testing.benchmark.compare
```
````

`````{py:class} PerfRecorder(suite: str, *, store: simvx.core.testing.benchmark.HistoryStore | None = None, tol: float = DEFAULT_TOLERANCE, update_baseline: bool = False, report_only: bool = False, emit: collections.abc.Callable[[str], None] = print)
:canonical: simvx.core.testing.benchmark.PerfRecorder

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecorder
```

```{rubric} Initialization
```

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecorder.__init__
```

````{py:method} record(result: simvx.core.testing.benchmark.BenchmarkResult, *, tol: float | None = None) -> str
:canonical: simvx.core.testing.benchmark.PerfRecorder.record

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecorder.record
```

````

````{py:method} finish() -> None
:canonical: simvx.core.testing.benchmark.PerfRecorder.finish

```{autodoc2-docstring} simvx.core.testing.benchmark.PerfRecorder.finish
```

````

`````

````{py:function} make_perf_recorder(suite: str, *, update_baseline: bool = False, report_only: bool = False, tol: float = DEFAULT_TOLERANCE) -> simvx.core.testing.benchmark.PerfRecorder
:canonical: simvx.core.testing.benchmark.make_perf_recorder

```{autodoc2-docstring} simvx.core.testing.benchmark.make_perf_recorder
```
````

````{py:function} perf_pytest_addoption(parser) -> None
:canonical: simvx.core.testing.benchmark.perf_pytest_addoption

```{autodoc2-docstring} simvx.core.testing.benchmark.perf_pytest_addoption
```
````