API
High-Level Interface (Python)
Fire
Bases: ABC
Base class for seed filtering logic.
Subclass this and implement the purge method to filter
results inside the Rust execution loop.
purge(sprout)
abstractmethod
Criteria for discarding a sprout result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sprout
|
Sprout
|
The current sprout state. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the sprout should be excluded, False to keep it. |
Nursery
Static class to convert Planter results (sprouts raw) into a dataframe.
pandas(data, expanded=False)
staticmethod
Converts planter sprout results into a pandas DataFrame.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
List[Tuple[int, Dict[int, int]]]
|
List of raw sprout data from Planter.find_seeds() |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame |
Planter
Bases: PlanterLab, ABC
Main entry point for seed simulations.
Inherit from this class and override the plant method to define
how your sprouts evolve buds.
find_seeds(fire=None, minimum=0, maximum=100000)
Executes a high-speed search across a range of seeds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fire
|
Optional[Fire]
|
An optional filter object with a |
None
|
minimum
|
int
|
Starting seed index. |
0
|
maximum
|
int
|
Ending seed index. |
100000
|
Returns:
| Type | Description |
|---|---|
List[Tuple[int, Dict[int, int]]]
|
A list of tuples containing the valid seed and its bud results. |
plant(sprout)
abstractmethod
Defines the evolution logic for a single sprout.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sprout
|
Sprout
|
The sprout instance to modify. |
required |
Sprout
A high-performance container for bud data and random growth logic.
This class wraps a Rust-based Sprout object to ensure maximum execution speed during heavy simulation loops.
Attributes:
| Name | Type | Description |
|---|---|---|
seed |
int
|
The unique seed value used to initialize the RNG. |
seed
property
Returns the current seed of the sprout.
__init__(seed)
Initializes a new Sprout.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
seed
|
int
|
The numerical seed for random number generation. |
required |
add_bud(name, count=1)
Adds a named bud to the collection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
int
|
The identifier for the bud. |
required |
count
|
Optional[int]
|
How many units to add. Defaults to 1. |
1
|
get_bud_count(key)
Gets the count of a specific bud on the sprout.
Returns:
| Type | Description |
|---|---|
int
|
The integer count of the bud on the sprout. |
growth(a, b)
Generates a random growth factor using the internal Rust PRNG.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a
|
int
|
The lower inclusive bound. |
required |
b
|
int
|
The upper inclusive bound. |
required |
Returns:
| Type | Description |
|---|---|
int
|
A random integer between a and b. |
to_dict()
Converts the internal bud collection to a Python dictionary.
Returns:
| Type | Description |
|---|---|
Dict[int, int]
|
A dictionary of bud names and their counts. |
Rust Interface
Sprout
A high-performance state container for seed simulation.
The Sprout holds the internal RNG state and a collection of 'buds' (event counts). It is designed to be passed between the Planter (logic) and Fire (filter).
seed
instance-attribute
The u64 seed used to initialize this specific sprout's RNG.
__init__(seed)
Initializes a new Sprout.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
seed
|
int
|
The initial u64 seed for deterministic randomness. |
required |
add_bud(bud_id, count=None)
Registers a count for a specific bud ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bud_id
|
int
|
A unique identifier for the event/item being tracked. |
required |
count
|
int
|
The amount to increment by. Defaults to 1. |
None
|
get_bud_count(bud_id)
Retrieves the current count for a bud ID without Python overhead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bud_id
|
int
|
The ID to look up. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
int |
int
|
The current count, or 0 if the ID has not been added. |
growth(a, b)
Generates a random integer within an inclusive range using the internal PRNG.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
a
|
int
|
Inclusive lower bound. |
required |
b
|
int
|
Inclusive upper bound. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
int |
int
|
A pseudo-random integer. |
reset(new_seed)
Resets the sprout state to allow memory reuse in tight loops.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
new_seed
|
int
|
The new seed to re-initialize the PRNG. |
required |
to_dict()
Exports the internal bud mapping to a Python dictionary.
Returns:
| Name | Type | Description |
|---|---|---|
dict |
Dict[int, int]
|
A dictionary mapping bud_ids to their respective counts. |
PlanterLab
The execution engine for batch-processing and filtering sprouts.
PlanterLab handles the heavy lifting of iterating through seed ranges in compiled code while calling back to Python for custom logic.
__init__()
find_seeds(fire=None, minimum=0, maximum=100000)
Orchestrates a search loop across a range of seeds.
This method iterates from minimum to maximum, creating a Sprout for each seed, executing 'plant', and checking the 'fire' filter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fire
|
Fire
|
A filter object with a 'purge' method. |
None
|
minimum
|
int
|
The starting seed (inclusive). |
0
|
maximum
|
int
|
The ending seed (exclusive). |
100000
|
Returns:
| Type | Description |
|---|---|
List[Tuple[int, Dict[int, int]]]
|
list[tuple[int, dict]]: A list of tuples containing (seed, results_dict). |
plant(sprout)
Interface method for defining bud growth logic.
Users should subclass PlanterLab and override this method in Python.