NuCon/README.md

# NuCon (Nucleares Controller)

NuCon is a Python library designed to interface with and control parameters in Nucleares, a nuclear reactor simulation game. It provides a robust, type-safe foundation for reading and writing game parameters, allowing users to easily create their own automations and control systems.

NuCon further provides a work in progress implementation of a reinforcement learning environment for training control policies.

## Features

- Enum-based parameter system for type safety and code clarity
- Support for various parameter types including floats, integers, booleans, strings, and custom enums
- Read and write capabilities for game parameters
- Custom truthy values for status enums to simplify conditional logic
- Dummy mode for testing without connecting to the game
- Batch operations for getting multiple parameters at once

## Installation

To install NuCon, clone this repository and install via pip:
```bash
pip install -e .
```

## Usage

Here's a basic example of how to use NuCon:

```python
from nucon import Nucon, BreakerStatus

# Set the base URL for the game's API (if different from default)
Nucon.set_base_url("http://localhost:8080/")

# Enable dummy mode for testing (optional)
Nucon.set_dummy_mode(True)

# Read a parameter
core_temp = Nucon.CORE_TEMP.value
print(f"Core Temperature: {core_temp}")

# Read a parameter with an enum type
pump_status = Nucon.COOLANT_CORE_CIRCULATION_PUMP_0_STATUS.value
print(f"Pump 0 Status: {pump_status}")

# Write to a parameter
Nucon.GENERATOR_0_BREAKER.value = BreakerStatus.OPEN # or True
print(f"Generator 0 Breaker Status: {Nucon.GENERATOR_0_BREAKER.value}")

# Use custom truthy values
if Nucon.COOLANT_CORE_CIRCULATION_PUMP_0_STATUS.value:
    print("Pump 0 is active")
```

## API Reference

The `Nucon` enum contains all available parameters. Each parameter is defined with:
- An ID (string)
- A type (float, int, bool, str, or a custom Enum)
- A boolean indicating whether it's writable

Parameter properties:
- `Nucon.<PARAMETER>.value`: Get or set the current value of the parameter. Assigning a new value will write it to the game.
- `Nucon.<PARAMETER>.param_type`: Get the type of the parameter
- `Nucon.<PARAMETER>.is_writable`: Check if the parameter is writable
- `Nucon.<PARAMETER>.enum_type`: Get the enum type of the parameter if it's an enum, otherwise None

Parameter methods:
- `Nucon.<PARAMETER>.read()`: Get the current value of the parameter (alias for `value`)
- `Nucon.<PARAMETER>.write(new_value, force=False)`: Write a new value to the parameter. `force` will try to write even if the parameter is known as non-writable or out of known allowable range.

Class methods:
- `Nucon.get(parameter)`: Get the value of a specific parameter. Also accepts string parameter names.
- `Nucon.set(parameter, value, force=False)`: Set the value of a specific parameter. Also accepts string parameter names. `force` will try to write even if the parameter is known as non-writable or out of known allowable range.
- `Nucon.get_all_readable()`: Get a list of all readable parameters (which is all parameters)
- `Nucon.get_all_writable()`: Get a list of all writable parameters
- `Nucon.get_all()`: Get all parameter values as a dictionary
- `Nucon.get_multiple(params)`: Get values for multiple specified parameters
- `Nucon.set_base_url(url)`: Set the base URL for the game's API
- `Nucon.set_dummy_mode(dummy_mode)`: Enable or disable dummy mode for testing

Custom Enum Types:
- `PumpStatus`: Enum for pump status (INACTIVE, ACTIVE_NO_SPEED_REACHED, ACTIVE_SPEED_REACHED, REQUIRES_MAINTENANCE, NOT_INSTALLED, INSUFFICIENT_ENERGY)
- `PumpDryStatus`: Enum for pump dry status (ACTIVE_WITHOUT_FLUID, INACTIVE_OR_ACTIVE_WITH_FLUID)
- `PumpOverloadStatus`: Enum for pump overload status (ACTIVE_AND_OVERLOAD, INACTIVE_OR_ACTIVE_NO_OVERLOAD)
- `BreakerStatus`: Enum for breaker status (OPEN, CLOSED)

## Reinforcement Learning (Work in Progress)

NuCon includes a preliminary Reinforcement Learning (RL) environment based on the OpenAI Gym interface. This feature is currently a work in progress and requires additional dependencies.

### Additional Dependencies

To use the RL features, you'll need to install the following packages:

```bash
pip install gymnasium numpy
```

### RL Environment

The `NuconEnv` class in `nucon/rl.py` provides a Gym-compatible environment for reinforcement learning tasks in the Nucleares simulation. Key features include:

- Observation space: Includes all readable parameters from the Nucon system.
- Action space: Encompasses all writable parameters in the Nucon system.
- Step function: Applies actions to the Nucon system and returns new observations.
- Objective function: Allows for predefined or custom objective functions to be defined for training.

### Usage

Here's a basic example of how to use the RL environment:
```python
from nucon.rl import NuconEnv, Parameterized_Objectives

env = NuconEnv(objectives=['max_power'], seconds_per_step=5)
# env2 = gym.make('Nucon-max_power-v0')
# env3 = NuconEnv(objectives=[Parameterized_Objectives['target_temperature'](goal_temp=600)], objective_weights=[1.0], seconds_per_step=5)

obs, info = env.reset()
for _ in range(1000):
    action = env.action_space.sample()  # Your agent here (instead of random)
    obs, reward, terminated, truncated, info = env.step(action)

    if terminated or truncated:
        obs, info = env.reset()
env.close()
```

Objectives takes either strings of the name of predefined objectives, or lambda functions which take an observation and return a scalar reward. Final rewards are (weighted) summed across all objectives. `info['objectives']` contains all objectives and their values.

## Testing

NuCon includes a test suite to verify its functionality and compatibility with the Nucleares game. 

### Running Tests

To run the tests:

1. Ensure the Nucleares game is running and accessible at http://localhost:8080/ (or update the URL in the test setup).
2. Install pytest: `pip install pytest`
3. Run the tests: `pytest test/test.py`

### Test Coverage

The tests verify:

- Parameter types match their definitions in NuCon
- Writable parameters can be written to
- Non-writable parameters cannot be written to, even when force-writing
- Enum parameters and their custom truthy values behave correctly

## Disclaimer
NuCon is an unofficial tool and is not affiliated with or endorsed by the creators of Nucleares.

## Citing
What? Why would you wanna cite it? What are you even doing?
```
@misc{nucon,
  title = {NuCon},
  author = {Dominik Roth},
  abstract = {NuCon is a Python library to interface with and control Nucleares, a nuclear reactor simulation game. Includes gymnasium bindings for Reinforcement Learning.}
  url = {https://git.dominik-roth.eu/dodox/NuCon},
  year = {2024},
}
```