Cases

Directory layout

Cases live in two sub-packages that mirror the grid type:

powerzoo/case/
├── transmission/   # Case5, Case14, Case118, Case300, Case29GB, ...
├── distribution/   # Case33bw, Case123, Case141, Case533mt_*, ...
├── CaseBase.py     # ClearCase base class
└── _registry.py    # list_cases() discovery

Loading a case

powerzoo.case.load_case(case_id, case_source='', mock=True, grid_type=None)

Load a power system case by name or file path.

Parameters:

Name	Type	Description	Default
case_id		Case identifier. Accepted forms: - Integer or string (e.g. 5, 'Case5', 'case5', 'case33bw'): loads the matching built-in Python case file. The case prefix is case-insensitive. - String ending in '.m': treated as a MATPOWER case file path and converted on-the-fly.	required
case_source		(deprecated) Sub-directory inside case/ to search.	''
mock		Passed to the case constructor (enables CaseMocker).	True
grid_type		Optional. 'transmission' or 'distribution'. Restricts lookup to the corresponding sub-directory and emits a warning if the loaded case's GRID_TYPE does not match.	None

Returns:

Type	Description
	ClearCase instance.

from powerzoo.case import load_case

case = load_case(5)                             # integer shorthand
case = load_case("Case5")                       # explicit name (case-insensitive after the prefix)
case = load_case("case33bw", grid_type="distribution")
case = load_case("path/to/case30.m")            # MATPOWER .m file

load_case accepts: an integer (5 → Case5); a string 'Case5', 'case5' or '5'; or a path to a MATPOWER .m file. Pass grid_type='transmission' or grid_type='distribution' to restrict the search and warn on mismatch.

Discovering available cases

from powerzoo.case import list_cases

all_cases = list_cases()                         # everything under transmission/ + distribution/
dist_only = list_cases(grid_type="distribution") # distribution-only
big_cases = list_cases(min_buses=100)            # cases with ≥100 buses

Each entry is a CaseMeta dataclass with fields: name, module_path, grid_type, bus_count, phase, voltage_level, source, description.

Case metadata attributes

Every ClearCase subclass declares class-level metadata:

Attribute	Type	Values	Description
GRID_TYPE	str	"transmission", "distribution"	Grid category
BUS_COUNT	int		Number of buses
PHASE	str	"1", "3"	Single-phase or three-phase
VOLTAGE_LEVEL	str	"HV", "MV", "LV"	Voltage level class
SOURCE	str	"MATPOWER", "custom", "CSV"	Data origin
DESCRIPTION	str		One-line description

ClearCase base class

powerzoo.case.CaseBase.ClearCase(mock=True)

Bases: object

Base class for power market clearing cases

Contains basic data for nodes, units, lines and loads, along with matrix computations and data processing methods.

Subclasses should override the class-level metadata attributes below to enable automatic discovery, filtering, and compatibility validation.

Initialize clearing case

init()

Initialize case data

Set node ID mapping and basic flags.

Returns:

Type	Description
ClearCase	self to support method chaining

get_node_gsdf()

Get node GSDF matrix (cached)

Returns:

Type	Description
DataFrame	generation shift distribution factor matrix per node

get_nodes_units_map()

Get node-to-units mapping matrix

Returns:

Type	Description
ndarray	node-to-units mapping matrix

get_nodes_loads_map()

Get node-to-loads mapping matrix

Returns:

Type	Description
ndarray	node-to-loads mapping matrix

get_nodes_id(*args)

Get node ID mapping

Parameters:

Name	Type	Description	Default
*args		node ID arrays	()

Returns:

Type	Description
List[ndarray]	list of mapped node IDs