Firing Script Module

class chipfiring.CFiringScript.CFiringScript(graph: CFGraph, script: Dict[str, int] | None = None)

Bases: object

Represents a chip-firing script for a given graph.

A firing script specifies a net number of times each vertex fires. Positive values indicate lending (firing), while negative values indicate borrowing.

__init__(graph: CFGraph, script: Dict[str, int] | None = None)

Initialize the firing script.

Parameters:

• graph – The CFGraph object the script applies to.

• script – A dictionary mapping vertex names (strings) to integers. Positive integers represent lending moves (firings). Negative integers represent borrowing moves. Vertices not included in the script are assumed to have 0 net firings. If None, an empty script will be created (default: None).

Raises:

ValueError – If any vertex name in the script is not present in the graph.

Example

>>> vertices = {"v1", "v2", "v3"}
>>> edges = [("v1", "v2", 1), ("v2", "v3", 2)]
>>> graph = CFGraph(vertices, edges)
>>> script_dict = {"v1": 2, "v3": -1}  # v1 fires twice, v3 borrows once
>>> firing_script = CFiringScript(graph, script_dict)
>>> firing_script.script
{'v1': 2, 'v3': -1, 'v2': 0}  # v2 has 0 firings by default

>>> # Empty script
>>> empty_script = CFiringScript(graph, {})
>>> empty_script.script
{'v1': 0, 'v2': 0, 'v3': 0}

get_firings(vertex_name: str) → int

Get the number of firings for a given vertex.

Returns 0 if the vertex is not explicitly mentioned in the script.

Parameters:

vertex_name – The name of the vertex.

Returns:

The net number of firings for the vertex.

Raises:

ValueError – If the vertex name is not present in the graph.

Example

>>> vertices = {"v1", "v2", "v3"}
>>> edges = [("v1", "v2", 1), ("v2", "v3", 2)]
>>> graph = CFGraph(vertices, edges)
>>> script_dict = {"v1": 5, "v2": -3}
>>> firing_script = CFiringScript(graph, script_dict)
>>> firing_script.get_firings("v1")
5
>>> firing_script.get_firings("v2")
-3
>>> firing_script.get_firings("v3")  # Not explicitly in script
0

set_firings(vertex_name: str, firings: int) → None

Set the number of firings for a given vertex.

Parameters:

• vertex_name – The name of the vertex.

• firings – The net number of firings to set for the vertex.

Raises:

ValueError – If the vertex name is not present in the graph.

Example

>>> vertices = {"v1", "v2", "v3"}
>>> edges = [("v1", "v2", 1), ("v2", "v3", 2)]
>>> graph = CFGraph(vertices, edges)
>>> firing_script = CFiringScript(graph, {})
>>> firing_script.set_firings("v1", 3)
>>> firing_script.get_firings("v1")
3
>>> firing_script.set_firings("v2", -2)
>>> firing_script.script
{'v1': 3, 'v2': -2, 'v3': 0}

update_firings(vertex_name: str, additional_firings: int) → None

Update the number of firings for a given vertex by adding to the current value.

Parameters:

• vertex_name – The name of the vertex.

• additional_firings – The number of firings to add (can be negative to reduce firings).

Raises:

ValueError – If the vertex name is not present in the graph.

Example

>>> vertices = {"v1", "v2", "v3"}
>>> edges = [("v1", "v2", 1), ("v2", "v3", 2)]
>>> graph = CFGraph(vertices, edges)
>>> script_dict = {"v1": 1}
>>> firing_script = CFiringScript(graph, script_dict)
>>> firing_script.update_firings("v1", 2)  # Add 2 more firings
>>> firing_script.get_firings("v1")
3  # 1 + 2
>>> firing_script.update_firings("v2", -1)  # Add -1 (borrow once)
>>> firing_script.get_firings("v2")
-1  # 0 + (-1)

to_dict() → Dict[str, Any]

Converts the CFiringScript instance to a dictionary representation.

Returns:

A dictionary with ‘graph’ and ‘script’ (mapping vertex names to firings).

classmethod from_dict(data: Dict[str, Any]) → CFiringScript

Creates a CFiringScript instance from a dictionary representation.

Parameters:

data – A dictionary with ‘graph’ (CFGraph representation) and ‘script’ (dictionary mapping vertex names to firings).

Returns:

A CFiringScript instance.

property script: Dict[str, int]

Return the script as a dictionary mapping vertex names to firings.

Returns:

A dictionary where keys are vertex names and values are the number of firings.

Example

>>> vertices = {"v1", "v2", "v3"}
>>> edges = [("v1", "v2", 1), ("v2", "v3", 2)]
>>> graph = CFGraph(vertices, edges)
>>> script_dict = {"v2": 10, "v3": -5}
>>> firing_script = CFiringScript(graph, script_dict)
>>> firing_script.script
{'v1': 0, 'v2': 10, 'v3': -5}