Metadata-Version: 2.4
Name: sydost-memvol
Version: 0.0.1
Summary: Toy emulator of memory volumes shared between virtual machines with access control and random workloads
Keywords: virtualization,memory,kvm,emulator,access-control
Author: Andrey Ferubko, Oleg Kazakov
Author-email: Andrey Ferubko <ferubko1999@yandex.ru>, Oleg Kazakov <kazakov@bgitu.ru>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: System :: Emulators
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/89605502155/sydost-memvol
Project-URL: Repository, https://github.com/89605502155/sydost-memvol
Project-URL: Changelog, https://github.com/89605502155/sydost-memvol/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# sydost-memvol

Toy emulator of **memory volumes** shared between virtual machines. A volume is a part of one VM's RAM
that other VMs may access through a protocol label (shared memory, RDMA, vhost-user) instead of memory
ballooning or hot-plug. The package is a teaching model: it does not touch hypervisors or real memory,
and all random processes come from a seeded generator.

Russian version: [README.ru.md](README.ru.md). Documentation: [docs/en/model.md](docs/en/model.md)
and [docs/ru/model.md](docs/ru/model.md).

## Install

```bash
pip install sydost-memvol
```

Python 3.11 to 3.14. No runtime dependencies.

## Quick start

```python
from sydost_memvol import SimConfig, VirtualMachine, simulate

vms = [VirtualMachine(f"vm{i}", ram_gb=32.0, export_share=0.5) for i in range(1, 5)]
result = simulate(vms, SimConfig(steps=200, seed=1, revoke_lag=2, attack_rate=0.05))
print(result.summary["mean_utilization"], result.summary["shortage_gb_steps"])
```

Command line:

```bash
python -m sydost_memvol --vms 4 --ram 32 --steps 200 --seed 1
```

## What the model contains

- `VirtualMachine`: name, RAM in GB, share of idle memory it exports.
- `MemoryVolume` and `Grant`: a volume owned by one VM, grants with rights `ro` or `rw` and an optional
  revocation step.
- `VolumeManager`: one step of the policy. It sizes volumes from the previous step's demand, borrows
  memory for shortages and schedules revocation after `revoke_lag` steps.
- `DemandProcess`: mean-reverting random demand with bursts.
- `simulate`: a run that also draws access attempts and classifies them as blocked, inside the
  revocation window (exposed), or legitimate.

## Limits

Outputs are model outputs, not measurements. The protocol label does not change any calculation.
Attack attempts are only counted. The package contains no exploit code.

## Development

```bash
uv sync
uv run ruff check .
uv run pytest
```

## License

MIT. Authors: Andrey Ferubko and Oleg Kazakov (Bryansk State Engineering-Technological University).
