semvec/pypi-packages huggingface dataset:
snowdrop-tangled-agents 0.0.5
Agents for the Tangled game
License: MIT
Requires Python: <3.14,>=3.11

# snowdrop-tangled-agents
A place to build and test agents for playing Tangled!

## How to build your own agent
This repo includes a random agent (see `RandomRandyAgent` in `random_agent.py`). To build your
own agent, follow the instructions and pattern for that agent. The process is straightforward - your
agent gets a Game instance as input/observable, which is a snapshot of the current game being played 
which includes the current state of the game, and you output an action/move. The move is just which 
edge to pick, and what color to apply to it. That's all! Obviously the underlying process you use to 
select this move can be arbitrarily complex but the actual agent interface is simple.

## Testing agents
A test script is included in `run_local_parallel_tournament.py`. Out of the box it runs 100,000 games
for each of the X-Prize graphs (not including the mutant C60 graph) where the adjudicator used is
simulated annealing, and the two agents in the competition are both random agents.

## Suggested next steps
If you want to build your own agent, I would start by building your own adjudicator (look at both
the adjudicators in the `snowdrop-adjudicators` repo). The better you
can spoof the D-Wave hardware, the better quality reward your agent will have to learn from. To do this,
I would recommend you build a look-up table adjudicator, by first enumerating all the terminal states
for a small game graph, and then adjudicating all of them using the schrodinger equation adjudicator (this will
be limited to small game graphs, but it's still a great warm-up for doing something more ambitious). Once
you have your lookup table adjudicator, you can then build an agent that uses it to give you the correct
answer every time. You can use `run_local_parallel_tournament.py` - add your adjudicator and new agents to
and see how well they do against the random agent and any other agents you might have built!
snowdrop-adjudicators 0.1.0
Two public adjudicators for the Tangled game
License: MIT
Requires Python: <3.14,>=3.11

# snowdrop-adjudicators
This contains two public adjudicators for the Tangled game, one using the Schrödinger equation and one
using simulated annealing. The Schrödinger equation adjudicator matches the ground truth output of the
quantum annealer for all problem instances up to the largest sizes I've been able to test (all the
terminal states of all the X-Prize graphs except the Petersen and Mutant C60 graph), whereas the simulated annealing
solver, while enormously faster, makes deterministic adjudication errors as described in the 
[X-Prize Phase 1 Submission document](https://fqodzpifyovgmqjlluin.supabase.co/storage/v1/object/public/pdfs/XPRIZE_Phase_I_Submission_Snowdrop.pdf).
The simulated annealing solver's parameters were chosen to give unbiased sampling of all classically degenerate 
ground states of the diagonal Ising model part of the Hamiltonian, which fails to accurately compute game scores
for some terminal states due to not taking into account order-by-disorder effects.

## Using these adjudicators
Both included adjudicators have parameters that you need to set. To see the minimum number and type of
these for both, look at `test_schrodinger.py` and `test_simulated_annealing.py` which show how to set these
parameters and how to use the adjudicators themselves. To see the full suite of settable parameters, look at the
`schrodinger.py` and `simulated_annealing.py` files.

## What will happen if I train an agent using these adjudicators?
If you use the Schrödinger adjudicator, your agent will be learning from the ground truth, but you will be limited
to very small graphs, and training could take forever. If you want to go this route, you should enumerate all possible
terminal states for your graph, use the Schrödinger adjudicator to adjudicate all of them, and store the results in 
a lookup table. You can then create a new lookup table adjudicator (see next section) which will then be very fast.

If you use the simulated annealing adjudicator, you will get very fast results, but they will be systematically
wrong for some fraction of the terminal states. The more frustration in the ground states of your instance, the more
potential there is for getting a wrong answer. If you train an agent using this adjudicator, it will learn from a
corrupted reward signal and may perform poorly.

## Building your own adjudicators
If you have an idea for how to spoof the quantum annealing hardware more effectively, for example using
tensor networks, you can build your own adjudicator. Just follow the pattern in `simulated_annealing.py`. 
Subclass the `Adjudicator` base class, define the adjudicator's parameters and a setup method, and then 
define your adjudication method. Ensure that the adjudicate method takes a `GameState` instance as input 
and returns an `AdjudicationResult` object as output.

## Running unit tests
There are two unit tests here, one per adjudicator. If you build a new adjudicator I strongly recommend following the
unit test pattern here and adding the exact same type of test for your new adjudicator.