citylearn.internal.entity_interface module

Canonical entity observation/action contract for CityLearnEnv.

class citylearn.internal.entity_interface.ChargerRef(row: int, building_index: int, building_name: str, charger_id: str, global_id: str)

Bases: object

Resolved charger location inside the environment.

building_index: int

building_name: str

charger_id: str

global_id: str

row: int

class citylearn.internal.entity_interface.CityLearnEntityInterfaceService(env)

Bases: object

Build and parse canonical entity payloads.

ACTION_FEEDBACK_BUNDLE = 'entity_action_feedback'

ACTION_FEEDBACK_FEATURES = ['last_requested_action_normalized', 'last_limited_action_normalized', 'last_requested_power_kw', 'last_limited_power_kw', 'last_applied_power_kw', 'last_projection_error_kw', 'applied_energy_prev_15m_kwh', 'applied_power_mean_prev_15m_kw', 'time_since_last_nonzero_action_hours', 'clip_reason_availability', 'clip_reason_power_limit', 'clip_reason_soc_limit', 'clip_reason_building_headroom', 'clip_reason_phase_headroom', 'clip_reason_export_headroom', 'clip_reason_outage', 'clip_reason_deferrable_window']

BASE_BUNDLE = 'entity_base'

BASE_CHARGER_FEATURES = ['min_charging_power_kw', 'min_discharging_power_kw', 'charger_efficiency_ratio']

BASE_STORAGE_FEATURES = ['min_charge_power_kw', 'min_discharge_power_kw', 'efficiency_ratio', 'round_trip_efficiency_ratio']

COMMUNITY_BUNDLE = 'entity_community_operational'

COMMUNITY_DISTRICT_EXTRA_FEATURES = ['community_net_power_kw', 'community_net_energy_kwh_step', 'community_import_power_kw', 'community_import_energy_kwh_step', 'community_export_power_kw', 'community_export_energy_kwh_step', 'community_pv_power_kw', 'community_pv_energy_kwh_step', 'community_bess_power_kw', 'community_bess_energy_kwh_step', 'community_ev_power_kw', 'community_ev_energy_kwh_step', 'community_building_headroom_kw', 'community_building_export_headroom_kw', 'community_phase_headroom_kw', 'community_phase_export_headroom_kw', 'community_flexible_charge_power_capacity_kw', 'community_flexible_discharge_power_capacity_kw', 'community_flexible_charge_energy_capacity_kwh_step', 'community_flexible_discharge_energy_capacity_kwh_step', 'community_flexible_energy_to_full_kwh', 'community_flexible_energy_available_kwh', 'active_buildings_count', 'active_chargers_count', 'active_evs_count', 'topology_version']

CORE_BUILDING_EXTRA_FEATURES = ['net_power_kw', 'net_energy_kwh_step', 'import_power_kw', 'import_energy_kwh_step', 'export_power_kw', 'export_energy_kwh_step', 'load_power_kw', 'load_energy_kwh_step', 'pv_power_kw', 'pv_energy_kwh_step', 'pv_surplus_power_kw', 'pv_surplus_energy_kwh_step', 'bess_power_kw', 'bess_energy_kwh_step', 'ev_charging_power_kw', 'ev_charging_energy_kwh_step', 'electrical_storage_soc_ratio', 'charging_total_service_power_kw', 'building_import_headroom_kw', 'building_export_headroom_kw', 'import_phase_headroom_kw', 'export_phase_headroom_kw', 'flexible_charge_power_capacity_kw', 'flexible_discharge_power_capacity_kw', 'flexible_charge_energy_capacity_kwh_step', 'flexible_discharge_energy_capacity_kwh_step', 'flexible_energy_to_full_kwh', 'flexible_energy_available_kwh']

CORE_BUNDLE = 'entity_core_electrical'

DEFAULT_OBSERVATION_BUNDLES = {'entity_action_feedback': False, 'entity_community_operational': False, 'entity_core_electrical': False, 'entity_demand_response': False, 'entity_forecasts_derived': False, 'entity_forecasts_existing': False, 'entity_robustness': False, 'entity_temporal_derived': False}

DEFERRABLE_ACTION_FEEDBACK_FEATURES = ['last_start_requested', 'last_start_applied', 'start_blocked', 'clip_reason_availability', 'clip_reason_power_limit', 'clip_reason_soc_limit', 'clip_reason_building_headroom', 'clip_reason_phase_headroom', 'clip_reason_export_headroom', 'clip_reason_outage', 'clip_reason_deferrable_window']

DEFERRABLE_APPLIANCE_FEATURES = ['pending', 'running', 'can_start', 'deadline_missed', 'earliest_start_time_step', 'latest_start_time_step', 'deadline_time_step', 'hours_until_latest_start', 'hours_until_deadline', 'slack_steps', 'slack_ratio', 'urgency_ratio', 'cycle_duration_steps', 'cycle_energy_kwh', 'remaining_energy_kwh', 'current_step_energy_kwh', 'priority', 'must_run', 'cycle_average_power_kw', 'cycle_peak_power_kw', 'cycle_load_factor_ratio', 'cycle_peak_step_offset_ratio', 'remaining_duration_steps', 'remaining_duration_hours', 'cycle_remaining_fraction_ratio', 'hours_until_earliest_start', 'start_window_width_hours', 'start_energy_kwh_step', 'start_power_kw', 'must_start_now', 'remaining_average_power_kw', 'current_step_power_kw']

DEMAND_RESPONSE_BUNDLE = 'entity_demand_response'

DEMAND_RESPONSE_DISTRICT_FEATURES = ['dr_active', 'dr_issuer_code', 'dr_direction', 'dr_target_power_kw', 'dr_baseline_power_kw', 'dr_time_remaining_hours', 'dr_activation_price_eur_per_kwh', 'dr_shortfall_penalty_eur_per_kwh', 'dr_previous_delivered_power_kw', 'dr_previous_shortfall_power_kw']

DERIVED_FORECAST_BUILDING_SIGNALS = ('load', 'pv', 'net')

DERIVED_FORECAST_BUNDLE = 'entity_forecasts_derived'

DERIVED_FORECAST_DISTRICT_SIGNALS = ('load', 'pv', 'net')

EXTRA_CHARGER_FEATURES = ['commanded_power_kw', 'applied_power_kw', 'applied_energy_kwh_step', 'hours_until_departure', 'time_until_departure_ratio', 'energy_to_required_soc_kwh', 'required_average_power_kw', 'avg_power_to_departure_kw', 'charging_slack_kw', 'charging_priority_ratio', 'connected_ev_soc_min_ratio', 'connected_ev_energy_available_kwh', 'connected_ev_energy_to_full_kwh', 'can_charge', 'can_discharge', 'available_charge_power_kw', 'available_discharge_power_kw', 'available_charge_action_normalized', 'available_discharge_action_normalized', 'max_deliverable_energy_until_departure_kwh', 'departure_energy_margin_kwh', 'departure_feasibility_ratio', 'min_required_action_normalized', 'charge_efficiency_at_max_ratio', 'discharge_efficiency_at_max_ratio', 'incoming_ev_required_soc_departure', 'incoming_ev_departure_time_step', 'incoming_ev_hours_until_departure', 'incoming_ev_time_until_departure_ratio']

EXTRA_EV_FEATURES = ['soc_ratio', 'soc_min_ratio', 'soc_max_ratio', 'energy_available_kwh', 'energy_to_full_kwh']

EXTRA_STORAGE_FEATURES = ['electrical_storage_soc_ratio', 'max_charge_power_kw', 'max_discharge_power_kw', 'energy_to_full_kwh', 'energy_available_kwh', 'can_charge', 'can_discharge', 'available_charge_power_kw', 'available_discharge_power_kw', 'available_charge_action_normalized', 'available_discharge_action_normalized', 'available_charge_energy_kwh_step', 'available_discharge_energy_kwh_step', 'max_charge_energy_kwh_step', 'max_discharge_energy_kwh_step', 'charge_headroom_ratio', 'discharge_available_ratio', 'usable_soc_ratio', 'current_efficiency_ratio', 'degraded_capacity_kwh', 'soc_min_ratio']

FORECAST_BUNDLE = 'entity_forecasts_existing'

FORECAST_HORIZONS = (('15m', 900), ('1h', 3600), ('3h', 10800), ('6h', 21600), ('24h', 86400))

LEGACY_CHARGER_FEATURES = ['connected_state', 'incoming_state', 'connected_ev_soc', 'connected_ev_required_soc_departure', 'connected_ev_battery_capacity_kwh', 'connected_ev_departure_time_step', 'incoming_ev_estimated_soc_arrival', 'incoming_ev_estimated_arrival_time_step', 'last_charged_kwh', 'max_charging_power_kw', 'max_discharging_power_kw']

LEGACY_EV_FEATURES = ['soc', 'battery_capacity_kwh', 'depth_of_discharge_ratio']

LEGACY_STORAGE_FEATURES = ['soc', 'capacity_kwh', 'nominal_power_kw', 'electricity_consumption_kwh']

PV_FEATURES = ['generation_power_kw', 'generation_energy_kwh_step', 'installed_power_kw', 'generation_capacity_factor_ratio']

ROBUSTNESS_BUNDLE = 'entity_robustness'

ROBUSTNESS_DISTRICT_FEATURES = ['robustness_active', 'robustness_observation_corruption_count_previous', 'robustness_forecast_corruption_count_previous', 'robustness_action_corruption_count_previous', 'robustness_asset_unavailable_count']

TEMPORAL_BUILDING_FEATURES = ['net_energy_prev_1_kwh_step', 'net_energy_prev_3_mean_kwh_step', 'import_energy_prev_1_kwh_step', 'export_energy_prev_1_kwh_step', 'hour_sin', 'hour_cos', 'day_type_sin', 'day_type_cos', 'month_sin', 'month_cos', 'seconds_of_day_sin', 'seconds_of_day_cos', 'is_weekend']

TEMPORAL_BUNDLE = 'entity_temporal_derived'

TEMPORAL_DISTRICT_FEATURES = ['community_net_prev_1_kwh_step', 'community_net_prev_3_mean_kwh_step', 'hour_sin', 'hour_cos', 'day_type_sin', 'day_type_cos', 'month_sin', 'month_cos', 'seconds_of_day_sin', 'seconds_of_day_cos', 'is_weekend']

property action_space: Dict

invalidate()

Mark specs/layout as stale and rebuild on next access.

observation_payload() → Mapping[str, Any]

Return canonical entity observations for current env time step.

property observation_space: Dict

parse_actions(actions: Any) → List[Mapping[str, float]]

Parse canonical entity action payload into per-building action dicts.

reset()

Rebuild specs and reusable buffers for the current episode layout.

property specs: Mapping[str, Any]

class citylearn.internal.entity_interface.DeferrableApplianceRef(row: int, building_index: int, building_name: str, appliance_id: str, global_id: str)

Bases: object

Resolved deferrable appliance location inside the environment.

appliance_id: str

building_index: int

building_name: str

global_id: str

row: int

class citylearn.internal.entity_interface.PVRef(row: int, building_index: int, building_name: str, pv_id: str, global_id: str)

Bases: object

Resolved PV location inside the environment.

building_index: int

building_name: str

global_id: str

pv_id: str

row: int

class citylearn.internal.entity_interface.StorageRef(row: int, building_index: int, building_name: str, storage_id: str, global_id: str)

Bases: object

Resolved storage location inside the environment.

building_index: int

building_name: str

global_id: str

row: int

storage_id: str