vse-sim 0.1.0__tar.gz

vse_sim-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Barry Clark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

vse_sim-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include docs/INSTALL.md
+include docs/PUBLISHING.md
+include LICENSE

vse_sim-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+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.

vse_sim-0.1.0/README.md

@@ -0,0 +1,121 @@
+# 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.

vse_sim-0.1.0/compat.py

@@ -0,0 +1,47 @@
+"""Small compatibility helpers shared across the simulation modules."""
+
+from numbers import Number
+
+from numpy import ceil as numpy_ceil
+from numpy import floor as numpy_floor
+from numpy import mean as numpy_mean
+from numpy import median as numpy_median
+from numpy import sqrt as numpy_sqrt
+from numpy import std as numpy_std
+
+
+def as_builtin_scalar(value):
+    """Convert NumPy scalar values to their Python built-in equivalents."""
+    try:
+        return value.item()
+    except (AttributeError, ValueError):
+        return value
+
+
+def ceil(*args, **kwargs):
+    return as_builtin_scalar(numpy_ceil(*args, **kwargs))
+
+
+def floor(*args, **kwargs):
+    return as_builtin_scalar(numpy_floor(*args, **kwargs))
+
+
+def mean(*args, **kwargs):
+    return as_builtin_scalar(numpy_mean(*args, **kwargs))
+
+
+def median(*args, **kwargs):
+    return as_builtin_scalar(numpy_median(*args, **kwargs))
+
+
+def sqrt(*args, **kwargs):
+    return as_builtin_scalar(numpy_sqrt(*args, **kwargs))
+
+
+def std(*args, **kwargs):
+    return as_builtin_scalar(numpy_std(*args, **kwargs))
+
+
+def isnum(x):
+    """Return whether ``x`` is an instance of a numeric type."""
+    return isinstance(x, Number)