Metadata-Version: 2.4
Name: vse-sim
Version: 0.1.0
Summary: Voter Satisfaction Efficiency simulation tools for voting systems.
Author: VSE Sim contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/wclark/vse-sim
Project-URL: Documentation, http://electionscience.github.io/vse-sim/
Project-URL: Issues, https://github.com/wclark/vse-sim/issues
Project-URL: Repository, https://github.com/wclark/vse-sim
Keywords: elections,simulation,voting,voter satisfaction efficiency
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Requires-Dist: tomli; extra == "lint"
Requires-Dist: validate-pyproject; extra == "lint"
Provides-Extra: audit
Requires-Dist: pip-audit; extra == "audit"
Provides-Extra: build-check
Requires-Dist: check-wheel-contents; extra == "build-check"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: check-wheel-contents; extra == "dev"
Requires-Dist: nox; extra == "dev"
Requires-Dist: pip-audit; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: tomli; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: validate-pyproject; extra == "dev"
Provides-Extra: publish
Requires-Dist: build; extra == "publish"
Requires-Dist: twine; extra == "publish"
Dynamic: license-file

# Voter Satisfaction Efficiency

These are some methods for running VSE (Voter Satisfaction Efficiency)
simulations for various voting systems.

See [Voter Satisfaction Efficiency FAQ](http://electionscience.github.io/vse-sim/) for an explanation of the methods and results.

## Installing the code

Requirements: Python 3.10+, NumPy, SciPy.

For notebook and library-style usage, install the package into the active
environment:

    python -m pip install .

To install directly from GitHub:

    python -m pip install "vse-sim @ git+https://github.com/wclark/vse-sim.git@main"

That exposes the modern `vse_sim` package namespace:

    from vse_sim import CsvBatch, Mav, PolyaModel, Score, baseRuns, medianRuns

The legacy top-level modules remain installed and importable for existing
scripts and examples:

    from vse import CsvBatch
    from voterModels import PolyaModel

See [Notebook and GitHub installation](docs/INSTALL.md) for Jupyter examples,
GitHub install variants, and the future PyPI install path.

Testing uses doctests, which should make most things pretty self-documenting.
For development, install the project in editable mode with the test, lint, and
publishing helpers:

    python -m pip install -e ".[dev,publish]"

Optionally install the local Git hooks:

    pre-commit install

The main local readiness checks can also be run through Nox:

    nox

Then run the legacy doctest examples:

    python3 -m doctest methods.py
    python3 -m doctest voterModels.py
    python3 -m doctest dataClasses.py
    python3 vse.py

Run the full test and coverage gate:

    python -m pytest --doctest-modules --cov=. --cov-fail-under=100

To generate the same local coverage artifacts that CI uploads:

    python -m pytest --doctest-modules --cov=. --cov-fail-under=100 --cov-report=term-missing:skip-covered --cov-report=xml:coverage.xml --cov-report=html:htmlcov --junitxml=pytest-results.xml

To run lint and style checks locally:

    validate-pyproject pyproject.toml
    python -m ruff check .
    python -m ruff format --check .

To build and check package distributions locally:

    python -m build
    python -m twine check dist/*
    check-wheel-contents dist/*.whl

To audit runtime dependencies for known vulnerabilities:

    python -m pip_audit --skip-editable --progress-spinner off .

The GitHub Actions workflow runs the same coverage check on pushes, pull requests,
and manual dispatches. It uploads the HTML coverage report plus machine-readable
coverage and JUnit XML files as workflow artifacts.

The same workflow also builds the wheel and source distribution, installs the
wheel into a clean environment, checks the distributions with Twine, and uploads
the package artifacts.

The `Lint and Style` workflow validates `pyproject.toml`, then runs Ruff
formatting and lint checks on pushes, pull requests, and manual dispatches.

## Security automation

GitHub Actions also runs CodeQL code scanning for Python on pushes, pull
requests, a weekly schedule, and manual dispatches. Dependabot checks Python and
GitHub Actions dependencies weekly. Dependency review blocks pull requests that
introduce moderate or higher vulnerabilities, and the dependency audit workflow
runs `pip-audit` against the project dependencies.

## Running simulations

Try

    $ python3
    >>> from vse import CsvBatch, baseRuns, Mav, medianRuns, Score
    >>> from voterModels import PolyaModel
    >>> csvs = CsvBatch(PolyaModel(), [[Score(), baseRuns], [Mav(), medianRuns]], nvot=5, ncand=4, niter=3)
    >>> csvs.saveFile()

and look for the results in `SimResults1.csv`

## Repository layout

The root directory keeps the importable Python modules and common entry points so
older examples and direct imports keep working. Reference output snapshots live
in `data/`.

New code should prefer the `vse_sim` package namespace. The root-level modules
are kept for backward compatibility and as a useful regression target during the
packaging migration.

See [Publishing checklist](docs/PUBLISHING.md) for the remaining steps before a
public `pip install vse-sim` release.
