Environments¶

The envs package contains simulation environments for Sustain-Cluster sustainability optimization.

Main Module¶

Includes the environments.

Submodules¶

Includes the environments.

Environment Components¶

class envs.sustaindc.battery_env.BatteryEnvFwd(env_config)[source]¶

Bases: Env

CO2_footprint(dc_load, ci, a_t, discharge_energy)[source]¶

Calculates carbon footprint

Parameters:

dc_load (float) – Total energy consumption of the DC.
ci (float) – Carbon intensity at current time step.
a_t (string) – Agent’s action.
discharge_energy (float) – Amount of energy to be discharged

Returns:

Carbon footprint produced at the current time step (gCO2e)

Return type:

CO2_footprint (float)

charging_rate_modifier(battery)[source]¶

Calculates the battery state depending on the charging rate

Parameters:: battery (batt.Battery2) – Battery model
Returns:: Battery charging rate
Return type:: charging_rate (float)

discharging_rate_modifier(battery)[source]¶

Calculates the battery state depending on the discharging rate

Parameters:: battery (batt.Battery2) – Battery model
Returns:: Battery discharging rate
Return type:: discharging_rate (float)

get_battery_soc()[source]¶

Get the current battery state of charge

Returns:: Battery state of charge
Return type:: battery_soc float

reset(*, seed=None, options=None)[source]¶

Reset BatteryEnvFwd to initial state.

Parameters:

seed (int, optional) – Random seed.
options (dict, optional) – Environment options.

Returns:

Current state of the environmment info (dict): A dictionary that containing additional information about the environment state

Return type:

temp_state (List[float])

set_dcload(dc_load)[source]¶

Set the current DC energy consumption

Parameters:: float (dc_load) – DC energy consumption.

sigmoid(x)[source]¶

step(action_id)[source]¶

Step function :type action_id: :param action_id: the action id :type action_id: int

Returns:: Current state of the environmment reward (float): reward value. done (bool): A boolean value signaling the if the episode has ended. info (dict): A dictionary that containing additional information about the environment state
Return type:: obs (list)

update_ci(ci, ci_n)[source]¶: Sets internal CIs values.

update_state()[source]¶

Updates obsevation with current DC energy consumption

Returns:: normalized_observations (string)

class envs.sustaindc.battery_model.Battery2(capacity, current_load=0, eff_c=1, eff_d=1, c_lim=0.1, d_lim=1, upper_u=-0.04, upper_v=1, lower_u=0.01, lower_v=0)[source]¶

Bases: object

c_lim = 3¶

calc_max_charge(T_u)[source]¶

calc_max_discharge(T_u, dc_load)[source]¶

capacity = 0¶

charge(input_load, T_u)[source]¶

current_load = 0¶

d_lim = 3¶

discharge(output_load, T_u, dc_load)[source]¶

eff_c = 1¶

eff_d = 1¶

find_and_init_capacity(input_load)[source]¶

get_battery_soc()[source]¶: Returns the state of charge (0…1) of the battery

is_full()[source]¶

lower_lim_u = 0¶

lower_lim_v = 0¶

reset()[source]¶

upper_lim_u = 0¶

upper_lim_v = 1¶

class envs.sustaindc.datacenter_model.DataCenter_ITModel(num_racks, dc_memory_GB, rack_supply_approach_temp_list, rack_CPU_config, rack_GPU_config=None, max_W_per_rack=10000, DC_ITModel_config=None, chiller_sizing=False)[source]¶

Bases: object

calculate_cooling_tower_water_usage()[source]¶

Calculate the estimated water usage of the cooling tower.

This function uses the attributes set in the class to estimate the water usage based [Sharma, R.K., Shah, A., Bash, C.E., Christian, T., & Patel, C.D. (2009). Water efficiency management in datacenters: Metrics and methodology. 2009 IEEE International Symposium on Sustainable Systems and Technology, 1-6.] [Mohammed Shublaq, Ahmad K. Sleiti., (2020). Experimental analysis of water evaporation losses in cooling towers using filters] https://spxcooling.com/water-calculator/

compute_datacenter_IT_load_outlet_temp(ITE_load_pct_list, CRAC_setpoint, GPU_load_pct_list=None, MEMORY_load_pct_list=None)[source]¶: Optimized power and thermal model assuming all racks are identical and utilization is uniform.

total_datacenter_full_load()[source]¶: Calculate the total DC IT power consumption (CPU, GPU, and fan)

class envs.sustaindc.datacenter_model.Rack(server_config_list, gpu_config_list=None, max_W_per_rack=10000, rack_config=None)[source]¶

Bases: object

clamp_supply_approach_temp(supply_approach_temperature)[source]¶

Returns the clamped delta/ supply approach temperature between the range [3.8, 5.3]

Returns:: Supply approach temperature
Return type:: float

compute_instantaneous_pwr(inlet_temp, ITE_load_pct, GPU_load_pct=0)[source]¶

Calculate the power consumption of the whole rack at the current step

Parameters:

inlet_temp (float) – Room temperature
ITE_load_pct (float) – Current CPU usage
GPU_load_pct (float) – Current GPU usage (optional, defaults to 0)

Returns:

(cpu_power, itfan_power, gpu_power)

Return type:

tuple

compute_instantaneous_pwr_vecd(inlet_temp, ITE_load_pct, GPU_load_pct=0, MEMORY_load_pct=0)[source]¶

Calculate the power consumption of the whole rack at the current step in a vectorized manner

Parameters:

inlet_temp (float) – Room temperature
ITE_load_pct (float) – Current CPU usage
GPU_load_pct (float) – Current GPU usage (optional, defaults to 0)
mem_load_pct (float) – Current memory usage (optional, defaults to 0)

Returns:

(cpu_power, itfan_power, gpu_power)

Return type:

tuple

get_average_rack_fan_v()[source]¶

Calculate the average fan velocity for each rack

Returns:: Average fan flow rate for the rack
Return type:: (float)

get_current_rack_load()[source]¶

Returns the total power consumption of the rack

Returns:: Total power consumption of the rack
Return type:: float

get_total_rack_fan_v()[source]¶

Calculate the total fan velocity for each rack

Returns:: Total fan flow rate for the rack
Return type:: (float)

log_system_values(cpu_load, mem_load, gpu_load)[source]¶

Simple function to append CPU, memory, and GPU load values to a CSV file.

Parameters:

cpu_load (float) – CPU load percentage (0-100)
mem_load (float) – Memory load percentage (0-100)
gpu_load (float) – GPU load percentage (0-100)
csv_path (str) – Path to the CSV file

log_thermal_control_data(inlet_temp, fan_ratio, cpu_load, gpu_load, mem_load, cpu_power, gpu_power, fan_power)[source]¶: Logs thermal control data to CSV for analysis and visualization.

server_and_fan_init()[source]¶: Initialize the Server and Fan parameters for the servers in each rack with the specified data center configurations

class envs.sustaindc.datacenter_model.Server(full_load_pwr=None, idle_pwr=None, gpu_full_load_pwr=None, gpu_idle_pwr=None, server_config=None)[source]¶

Bases: object

compute_instantaneous_cpu_pwr(inlet_temp, ITE_load_pct)[source]¶

Calculate the CPU power consumption

Parameters:

inlet_temp (float) – Inlet temperature
ITE_load_pct (float) – CPU utilization

Returns:

CPU power consumption in Watts

Return type:

float

compute_instantaneous_fan_pwr(inlet_temp, ITE_load_pct)[source]¶

Calculate the IT fan power consumption

Parameters:

inlet_temp (float) – Inlet temperature
ITE_load_pct (float) – IT workload percentage

Returns:

Fan power consumption in Watts

Return type:

float

compute_instantaneous_gpu_pwr(gpu_utilization)[source]¶

Calculate GPU power based on utilization using the logarithmic model

Parameters:: gpu_utilization (float) – GPU utilization percentage (0-100)
Returns:: GPU power consumption in Watts
Return type:: float

cpu_curve1()[source]¶: initialize the cpu power ratio curve at different IT workload ratios as a function of inlet temperatures [3]

itfan_curve2()[source]¶: initialize the itfan velocity ratio curve at different IT workload ratios as a function of inlet temperatures [3]

envs.sustaindc.datacenter_model.calculate_HVAC_power(CRAC_setpoint, avg_CRAC_return_temp, ambient_temp, data_center_full_load, DC_Config, ctafr=None)[source]¶

Calculate the HVAC power attributes

Parameters:

CRAC_Setpoint (float) – The control action
avg_CRAC_return_temp (float) – The average of the temperatures from all the Racks + their corresponding return approach temperature (Delta)
ambient_temp (float) – outside air temperature
data_center_full_load (float) – total data center capacity

Returns:

CRAC fan power CT_Fan_pwr (float): Cooling tower fan power CRAC_cooling_load (float): CRAC cooling load Compressor_load (float): Chiller compressor load

Return type:

CRAC_Fan_load (float)

envs.sustaindc.datacenter_model.calculate_avg_CRAC_return_temp(rack_return_approach_temp_list, rackwise_outlet_temp)[source]¶

Calculate the CRAC return air temperature

Parameters:

rack_return_approach_temp_list (List[float]) – The delta change in temperature from each rack to the CRAC unit
rackwise_outlet_temp (float) – The outlet temperature of each rack

Returns:

CRAC return air temperature

Return type:

(float)

envs.sustaindc.datacenter_model.calculate_chiller_power(max_cooling_cap, load, ambient_temp)[source]¶

Calculate the chiller power consumption based on load and operating conditions.

Obtained from:

Parameters:

max_cooling_cap (float) – Maximum cooling capacity of the chiller (Watts).
load (float) – The heat load to be removed by the chiller (Watts).
ambient_temp (float) – Current ambient temperature (Celsius).

Returns:

Estimated power consumption of the chiller (Watts).

Return type:

float

envs.sustaindc.datacenter_model.chiller_sizing(DC_Config, total_mem_GB, min_CRAC_setpoint=16, max_CRAC_setpoint=22, max_ambient_temp=40.0)[source]¶

Calculates the chiller sizing for a data center based on the given configuration and parameters.

Parameters:

DC_Config (object) – The data center configuration object.
dc_memory_GB (float) – the total available memory in the datacenter.
min_CRAC_setpoint (float) – The minimum CRAC setpoint temperature in degrees Celsius. Default is 16.
max_CRAC_setpoint (float) – The maximum CRAC setpoint temperature in degrees Celsius. Default is 22.
max_ambient_temp (float) – The maximum ambient temperature in degrees Celsius. Default is 40.0.

Returns:

A tuple containing the cooling tower reference air flow rate (ctafr) and the rated load of the cooling tower (CT_rated_load).

Return type:

tuple

envs.sustaindc.datacenter_model.heat_recovery(max_IT_load, ambient_temp, DC_Config)[source]¶

class envs.sustaindc.dc_gym.dc_gymenv(observation_variables, dc_memory_GB, observation_space, action_variables, action_space, action_mapping, ranges, add_cpu_usage, add_gpu_usage, min_temp, max_temp, action_definition, DC_Config, seed=123, episode_length_in_time=None)[source]¶

Bases: Env

get_obs()[source]¶

Returns the observation at the current time step.

Returns:: Current state of the environmment.
Return type:: observation (List[float])

normalize(obs)[source]¶: Normalizes the observation.

reset(*, seed=None, options=None)[source]¶

Reset dc_gymenv to initial state.

Parameters:

seed (int, optional) – Random seed.
options (dict, optional) – Environment options.

Returns:

Current state of the environmment {} (dict): A dictionary that containing additional information about the environment state

Return type:

raw_curr_state (List[float])

set_ambient_temp(ambient_temp, wet_bulb)[source]¶: Updates the external temperature.

set_bat_SoC(bat_SoC)[source]¶: Updates the battery state of charge.

step(raw_curr_stpt)[source]¶

Makes an environment step in`dc_gymenv.

Parameters:: action_id (int) – Action to take.
Returns:: Current state of the environmment reward (float): reward value. done (bool): A boolean value signaling the if the episode has ended. info (dict): A dictionary that containing additional information about the environment state
Return type:: observations (List[float])

update_workloads(cpu_load, mem_load, gpu_load)[source]¶: Updates the current CPU, GPU amd MEMORY utilization. Fraction between 0.0 and 1.0

class envs.sustaindc.sustaindc_env.SustainDC(env_config)[source]¶

Bases: Env

can_schedule(task)[source]¶

get_current_carbon_intensity(norm=False)[source]¶: Helper method to get CI from the internal manager.

release_resources(current_time, logger)[source]¶: Releases resources from completed tasks and logs their completion.

reset(init_year=None, init_day=None, init_hour=None, seed=None, options=None)[source]¶

Reset the environment.

Parameters:

seed (int, optional) – Random seed.
options (dict, optional) – Environment options.

Returns:

Dictionary of states. infos (dict): Dictionary of infos.

Return type:

states (dict)

set_seed(seed=None)[source]¶: Set the random seed for the environment.

state()[source]¶

Get the state of the environment.

Returns:: State of the environment.
Return type:: np.ndarray

step(action_dict, logger)[source]¶

Step the environment.

Parameters:: action_dict – Dictionary of actions of each agent defined in self.agents.
Returns:: Dictionary of observations/states. rews (dict): Dictionary of rewards. terminated (dict): Dictionary of terminated flags. truncated (dict): Dictionary of truncated flags. infos (dict): Dictionary of infos.
Return type:: obs (dict)

try_to_schedule_task(task, current_time, logger)[source]¶

Attempts to schedule a task if sufficient resources are available.

If the task is successfully scheduled:

Resources are allocated.
The task is moved to the running queue.
Logs the scheduling details.

If resources are insufficient:

The task remains in the pending queue.
The system tracks how long the task has been waiting.
If the wait time exceeds MAX_WAIT_INTERVALS, the task is dropped.

Returns:

True if the task was scheduled.
False if the task was re-added to the pending queue.

class envs.sustaindc.timeloadshifting_env.CarbonLoadEnv(env_config={}, future=True, n_vars_ci=4, flexible_workload_ratio=0.2, n_vars_energy=0, n_vars_battery=1, test_mode=False, queue_max_len=500, initialize_queue_at_reset=False)[source]¶

Bases: Env

get_task_age_histogram(tasks_queue, current_day, current_hour)[source]¶

reset(*, seed=None, options=None)[source]¶

Reset CarbonLoadEnv to initial state.

Returns:: Current state of the environmment info (dict): A dictionary that containing additional information about the environment state
Return type:: observations (List[float])

step(action)[source]¶

Makes an environment step in CarbonLoadEnv.

Parameters:

action (float) –

Continuous action between -1 and 1. -1: Defer all shiftable tasks.

1: Process tasks from the DTQ to maximize utilization. Values between -1 and 0 defer a fraction of tasks, and values between 0 and 1 process a fraction of tasks in the DTQ.

Returns:

Current state of the environment. reward (float): Reward value. done (bool): A boolean signaling if the episode has ended. info (dict): A dictionary containing additional information about the environment state.

Return type:

state (List[float])

update_current_date(current_day, current_hour)[source]¶

Update the current hour in the environment.

Parameters:: current_hour (float) – Current hour in the environment.

update_workload(workload)[source]¶

Makes an environment step in`BatteryEnvFwd. Workload should be a float between 0 and 1.

Parameters:: workload (float) – Workload assigned at the current time step

Other Environment Components¶

class envs.env_config.EnvConfig(raw_config)[source]¶: Bases: dict

envs.env_config.get_default_config()[source]¶

class envs.task_scheduling_env.TaskSchedulingEnv(cluster_manager, start_time, end_time, reward_fn, writer=None)[source]¶

Bases: Env

RL Environment for global task scheduling across distributed datacenters.

This environment wraps around DatacenterClusterManager and exposes a Gym-compatible interface. It manages task-level actions (assignment or defer), computes observations, and tracks rewards via a modular reward function.

RL agents interact with this class.

reset(seed=None, options=None)[source]¶

Resets the environment to an initial internal state, returning an initial observation and info.

This method generates a new starting state often with some randomness to ensure that the agent explores the state space and learns a generalised policy about the environment. This randomness can be controlled with the seed parameter otherwise if the environment already has a random number generator and reset() is called with seed=None, the RNG is not reset.

Therefore, reset() should (in the typical use case) be called with a seed right after initialization and then never again.

For Custom environments, the first line of reset() should be super().reset(seed=seed) which implements the seeding correctly.

Changed in version v0.25: The return_info parameter was removed and now info is expected to be returned.

Parameters:

seed (optional int) – The seed that is used to initialize the environment’s PRNG (np_random) and the read-only attribute np_random_seed. If the environment does not already have a PRNG and seed=None (the default option) is passed, a seed will be chosen from some source of entropy (e.g. timestamp or /dev/urandom). However, if the environment already has a PRNG and seed=None is passed, the PRNG will not be reset and the env’s np_random_seed will not be altered. If you pass an integer, the PRNG will be reset even if it already exists. Usually, you want to pass an integer right after the environment has been initialized and then never again. Please refer to the minimal example above to see this paradigm in action.
options (optional dict) – Additional information to specify how the environment is reset (optional, depending on the specific environment)

Returns:

Observation of the initial state. This will be an element of observation_space: (typically a numpy array) and is analogous to the observation returned by step().
info (dictionary): This dictionary contains auxiliary information complementing observation. It should be analogous to: the info returned by step().

Return type:

observation (ObsType)

step(actions)[source]¶: actions: list[int] of length == len(self.current_tasks) Each element is the index of the destination datacenter (0-based)