Your first simulation

Install CityLearn as described in Installation, save the following code as first_simulation.py, and run python first_simulation.py.

from citylearn.agents.baseline import BusinessAsUsualAgent
from citylearn.citylearn import CityLearnEnv

env = CityLearnEnv(
    "citylearn_challenge_2022_phase_all_plus_evs",
    episode_time_steps=24,
    interface="flat",
    render_mode="none",
)
agent = BusinessAsUsualAgent(env)
observations, info = env.reset(seed=0)
terminated = truncated = False

while not (terminated or truncated):
    actions = agent.predict(observations)
    observations, rewards, terminated, truncated, info = env.step(actions)

kpis = env.evaluate_v2()
selected = [
    "district_cost_total_control_eur",
    "district_energy_grid_total_import_control_kwh",
    "district_ev_performance_departure_min_acceptable_feasible_ratio",
    "district_electrical_service_phase_violations_energy_total_kwh",
]
print(kpis.loc[
    (kpis["level"] == "district") & kpis["cost_function"].isin(selected),
    ["cost_function", "value"],
].to_string(index=False))
env.close()

What happens in this example?

  1. The environment resolves a public dataset by name. On first use it downloads the data from the official repository at the installed package’s version tag and caches it locally. Internet access is needed for that download; no repository clone or private dataset is required.

  2. reset(seed=0) starts the episode and returns observations plus information.

  3. The built-in BusinessAsUsualAgent selects actions. It charges connected EVs, starts ready flexible appliances and uses stationary storage for PV self-consumption. Its default EV target is full charge, not symmetric tracking of a lower requested departure SOC.

  4. step returns observations, rewards, termination, truncation and information, in that order. The loop stops when either termination flag is true.

  5. evaluate_v2() returns a table with cost_function, value, name and level columns. The example prints four district/community indicators: cost, imported energy, feasible EV minimum service and residual phase-limit violation energy.

This dataset uses hourly timesteps. The 24-state episode has 23 control transitions: the final state is the observation after the last action. Increase the episode window for a study covering more EV departures or service events.

Read the results

Start with total cost, imported energy, minimum EV departure service and electrical-limit violations. The How to read the scorecard explains these together, including the distinction between service and target-SOC accuracy. The KPIs Reference explains KPI families, units and baselines.

To save the full KPI table:

kpis.to_csv("kpis.csv", index=False)

evaluate_v2() includes a native business-as-usual comparison by default. Use include_business_as_usual=False when you only need the current run and the conventional baseline; see How to read the scorecard for the difference.

Next steps