# chipfiring
> Unified interface for visualization and analysis of chip firing games and related algorithms.
[](https://pypi.python.org/pypi/chipfiring/)
[](https://github.com/DhyeyMavani2003/chipfiring/actions/workflows/test.yaml)
[](https://chipfiring.readthedocs.io/en/latest/?badge=latest)
[](https://coveralls.io/github/DhyeyMavani2003/chipfiring?branch=master)
[](https://github.com/christophevg/pypi-template)
A Python implementation of the chip-firing game (also known as the dollar game) on graphs. This package provides a mathematical framework for studying and experimenting with chip-firing games, with a focus on the dollar game variant.
## Documentation
Visit [Read the Docs](https://chipfiring.readthedocs.org) for the full documentation, including overviews and several examples.
## Overview
The chip-firing game is a mathematical model that can be used to study various phenomena in graph theory, algebraic geometry, and other areas of mathematics. In the dollar game variant, we consider a graph where:
- Vertices represent people
- Edges represent relationships between people
- Each vertex has an integer value representing wealth (negative values indicate debt)
- Players can perform lending/borrowing moves by sending money across edges
The goal is to find a sequence of moves that makes everyone debt-free. If such a sequence exists, the game is said to be *winnable*.
## Installation
```bash
pip install chipfiring
```
## Usage
Here's a simple example of how to use the package:
```python
from chipfiring.graph import Graph, Vertex
from chipfiring.divisor import Divisor
from chipfiring.dollar_game import DollarGame
# Create vertices
alice = Vertex("Alice")
bob = Vertex("Bob")
charlie = Vertex("Charlie")
elise = Vertex("Elise")
# Create graph
G = Graph()
G.add_vertex(alice)
G.add_vertex(bob)
G.add_vertex(charlie)
G.add_vertex(elise)
# Add edges
G.add_edge(alice, bob)
G.add_edge(alice, charlie)
G.add_edge(alice, elise)
G.add_edge(bob, charlie)
G.add_edge(charlie, elise)
# Create initial wealth distribution
initial_divisor = Divisor(G, {
alice: 2,
bob: -3,
charlie: 4,
elise: -1
})
# Create and play the game
game = DollarGame(G, initial_divisor)
# Check if game is winnable
print(f"Is winnable? {game.is_winnable()}")
# Try some moves
game.fire_vertex(charlie) # Charlie lends
game.borrow_vertex(bob) # Bob borrows
game.fire_set({alice, elise, charlie}) # Set-firing move
# Check current state
print(f"Current wealth: {game.get_current_state()}")
print(f"Is effective? {game.is_effective()}")
```
## Mathematical Background
The implementation follows the mathematical formalization described in the LaTeX writeup, which includes:
1. **Graph Structure**: Finite, connected, undirected multigraphs without loop edges
2. **Divisors**: Elements of the free abelian group on vertices
3. **Laplacian Matrix**: Matrix representation of lending moves
4. **Linear Equivalence**: Equivalence relation on divisors
5. **Effective Divisors**: Divisors with non-negative values
6. **Winnability**: Property of being linearly equivalent to an effective divisor
## Features
- Mathematical graph implementation with support for multigraphs
- Divisor class with operations for lending and borrowing
- Laplacian matrix computations
- Linear equivalence checking
- Set-firing moves
- Comprehensive type hints and documentation
## Development
To set up the development environment:
```bash
# Clone the repository
git clone https://github.com/yourusername/chipfiring.git
cd chipfiring
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -r requirements.txt
pip install -r requirements.docs.txt
# Run tests
pytest
# Build documentation
cd docs
make html
```
## License
This project is licensed under the MIT License - see the [LICENSE](../LICENSE.txt) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": "https://github.com/DhyeyMavani2003/chipfiring",
"name": "chipfiring",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Dhyey Mavani",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/61/36/c18c380ae33d698aae897960ae460c57d0421571c74f5191065c918f7d19/chipfiring-1.1.3.tar.gz",
"platform": null,
"description": "# chipfiring\n\n> Unified interface for visualization and analysis of chip firing games and related algorithms.\n\n[](https://pypi.python.org/pypi/chipfiring/)\n[](https://github.com/DhyeyMavani2003/chipfiring/actions/workflows/test.yaml)\n[](https://chipfiring.readthedocs.io/en/latest/?badge=latest)\n[](https://coveralls.io/github/DhyeyMavani2003/chipfiring?branch=master)\n[](https://github.com/christophevg/pypi-template)\n\nA Python implementation of the chip-firing game (also known as the dollar game) on graphs. This package provides a mathematical framework for studying and experimenting with chip-firing games, with a focus on the dollar game variant.\n\n## Documentation\n\nVisit [Read the Docs](https://chipfiring.readthedocs.org) for the full documentation, including overviews and several examples.\n\n## Overview\n\nThe chip-firing game is a mathematical model that can be used to study various phenomena in graph theory, algebraic geometry, and other areas of mathematics. In the dollar game variant, we consider a graph where:\n\n- Vertices represent people\n- Edges represent relationships between people\n- Each vertex has an integer value representing wealth (negative values indicate debt)\n- Players can perform lending/borrowing moves by sending money across edges\n\nThe goal is to find a sequence of moves that makes everyone debt-free. If such a sequence exists, the game is said to be *winnable*.\n\n## Installation\n\n```bash\npip install chipfiring\n```\n\n## Usage\n\nHere's a simple example of how to use the package:\n\n```python\nfrom chipfiring.graph import Graph, Vertex\nfrom chipfiring.divisor import Divisor\nfrom chipfiring.dollar_game import DollarGame\n\n# Create vertices\nalice = Vertex(\"Alice\")\nbob = Vertex(\"Bob\")\ncharlie = Vertex(\"Charlie\")\nelise = Vertex(\"Elise\")\n\n# Create graph\nG = Graph()\nG.add_vertex(alice)\nG.add_vertex(bob)\nG.add_vertex(charlie)\nG.add_vertex(elise)\n\n# Add edges\nG.add_edge(alice, bob)\nG.add_edge(alice, charlie)\nG.add_edge(alice, elise)\nG.add_edge(bob, charlie)\nG.add_edge(charlie, elise)\n\n# Create initial wealth distribution\ninitial_divisor = Divisor(G, {\n alice: 2,\n bob: -3,\n charlie: 4,\n elise: -1\n})\n\n# Create and play the game\ngame = DollarGame(G, initial_divisor)\n\n# Check if game is winnable\nprint(f\"Is winnable? {game.is_winnable()}\")\n\n# Try some moves\ngame.fire_vertex(charlie) # Charlie lends\ngame.borrow_vertex(bob) # Bob borrows\ngame.fire_set({alice, elise, charlie}) # Set-firing move\n\n# Check current state\nprint(f\"Current wealth: {game.get_current_state()}\")\nprint(f\"Is effective? {game.is_effective()}\")\n```\n\n## Mathematical Background\n\nThe implementation follows the mathematical formalization described in the LaTeX writeup, which includes:\n\n1. **Graph Structure**: Finite, connected, undirected multigraphs without loop edges\n2. **Divisors**: Elements of the free abelian group on vertices\n3. **Laplacian Matrix**: Matrix representation of lending moves\n4. **Linear Equivalence**: Equivalence relation on divisors\n5. **Effective Divisors**: Divisors with non-negative values\n6. **Winnability**: Property of being linearly equivalent to an effective divisor\n\n## Features\n\n- Mathematical graph implementation with support for multigraphs\n- Divisor class with operations for lending and borrowing\n- Laplacian matrix computations\n- Linear equivalence checking\n- Set-firing moves\n- Comprehensive type hints and documentation\n\n## Development\n\nTo set up the development environment:\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/chipfiring.git\ncd chipfiring\n\n# Create and activate virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install development dependencies\npip install -r requirements.txt\npip install -r requirements.docs.txt\n\n# Run tests\npytest\n\n# Build documentation\ncd docs\nmake html\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](../LICENSE.txt) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This is an Pythonic API for visualization and analysis of chip firing games and corresponding algorithms.",
"version": "1.1.3",
"project_urls": {
"Homepage": "https://github.com/DhyeyMavani2003/chipfiring"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "48e5a3bd41337b08bbcb523b84c924650308263868aa99c7ae5d71f3a16ad34a",
"md5": "387f10c856f8641e6f06049e79d36241",
"sha256": "36432bca40ad3824f08c662834cd6de35e2c6b19607d5cb3881e24c3faef94f0"
},
"downloads": -1,
"filename": "chipfiring-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "387f10c856f8641e6f06049e79d36241",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 118170,
"upload_time": "2025-08-10T18:39:29",
"upload_time_iso_8601": "2025-08-10T18:39:29.099925Z",
"url": "https://files.pythonhosted.org/packages/48/e5/a3bd41337b08bbcb523b84c924650308263868aa99c7ae5d71f3a16ad34a/chipfiring-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6136c18c380ae33d698aae897960ae460c57d0421571c74f5191065c918f7d19",
"md5": "9ffab9aa61794b5ccfd64dd64f32b597",
"sha256": "e2c5b50fb7f0a29a3ccd593e9bfbe53b4567ec7b7a80b308a709cb8ea24b1647"
},
"downloads": -1,
"filename": "chipfiring-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "9ffab9aa61794b5ccfd64dd64f32b597",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 106034,
"upload_time": "2025-08-10T18:39:30",
"upload_time_iso_8601": "2025-08-10T18:39:30.606716Z",
"url": "https://files.pythonhosted.org/packages/61/36/c18c380ae33d698aae897960ae460c57d0421571c74f5191065c918f7d19/chipfiring-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 18:39:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DhyeyMavani2003",
"github_project": "chipfiring",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": []
},
{
"name": "networkx",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "pytest-mock",
"specs": []
},
{
"name": "coverage",
"specs": []
},
{
"name": "black",
"specs": []
},
{
"name": "mypy",
"specs": []
},
{
"name": "ruff",
"specs": []
},
{
"name": "dash",
"specs": []
},
{
"name": "dash-cytoscape",
"specs": []
},
{
"name": "dash-bootstrap-components",
"specs": []
}
],
"tox": true,
"lcname": "chipfiring"
}
JSON
