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:

pip install -e .

Usage

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

from nucon import Nucon, BreakerStatus

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

# 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:

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:

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:8785/ (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},
}