164 lines
6.7 KiB
Markdown
164 lines
6.7 KiB
Markdown
# 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 allowed 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 allowed 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},
|
|
}
|
|
```
|