API Reference

runtdpf(case, data, load_names, price_profiles, irradiance_profiles, opt)

Run time-domain power flow analysis for multiple days with varying loads, prices, and solar irradiance.

Arguments

• case: Power system case data structure
• data: DataFrame containing load time series data
• load_names: Vector of load names
• price_profiles: Matrix containing electricity price data
• irradiance_profiles: Matrix containing solar irradiance data
• opt: Options for power flow calculation

Returns

• 3D array of results where dimensions represent [island, day, hour]

Description

This function performs time-domain power flow analysis across multiple days, considering varying loads, electricity prices, and solar irradiance. It processes the data day by day and handles multiple grid islands.

The function performs the following steps:

1. Determines the number of days from the time series data
2. Validates that the number of time points is divisible by 24 (hours per day)
3. Generates daily load, price, and irradiance data using helper functions
4. Converts the power system case to JPC format
5. Extracts grid islands from the power system
6. For each day and each island (in parallel):
   • Extracts the relevant load data for the island
   • Performs power flow calculations for each hour using the run_single_day function
7. Returns a 3D array of results organized by island, day, and hour

The parallel processing is implemented using Julia's threading capabilities (@threads), with the outer loop over days being parallelized for efficiency.

build_incidence_matrix_td(n_nodes, branchAC, branchDC, converter)

Build the incidence matrix for a hybrid AC-DC power system.

Arguments

• n_nodes: Total number of nodes in the system
• branchAC: Matrix containing AC branch data, with columns for from/to buses
• branchDC: Matrix containing DC branch data, with columns for from/to buses
• converter: Matrix containing converter data, with columns for AC/DC bus connections

Returns

• A: Incidence matrix where rows represent branches and columns represent nodes
• branch_data: Vector of tuples containing (fromnode, tonode, branchtype, originalindex) where branch_type is 1 for AC branches, 2 for DC branches, and 3 for converters

Description

This function constructs the node-branch incidence matrix for a hybrid AC-DC power system. The incidence matrix A has dimensions (nbranches × nnodes) where nbranches is the total number of branches (AC branches + DC branches + converters) and nnodes is the total number of nodes in the system.

For each branch connecting nodes i and j:

• A[branch, i] = 1 (outflow from node i is positive)
• A[branch, j] = -1 (inflow to node j is negative)

The function also returns branch_data, which provides information about each branch including its start and end nodes, type (AC, DC, or converter), and its original index in the input data. Branches are sorted by their starting node for consistent ordering.

plot_flow_violations(results, case, time_day, flow_limit = 3.0, plot_type = "summary", flow_direction = "max"; save_path = nothing, save_format = "pdf")

Plot power flow violations in power system branches.

Arguments

• results: Simulation results containing branch flow data
• case: Power system case data
• time_day: Number of days in the simulation
• flow_limit: Power flow limit in MW (default: 3.0)
• plot_type: Type of plot to generate:
  • "summary": Overall statistics of violations
  • "worst": Shows the worst branches with violations
  • "all": Shows all branches with violations
• flow_direction: How to evaluate flow violations:
  • "max": Maximum absolute value of flow in either direction
  • "both": Same as "max"
  • "forward": Only check flow from from-bus to to-bus
  • "reverse": Only check flow from to-bus to from-bus
• save_path: Optional path to save the plot
• save_format: Format to save the plot (default: "pdf")

Returns

• plot_result: The generated plot
• violation_count: Number of branches with violations at each time point
• max_violation_percent: Maximum violation percentage at each time point
• total_violation_severity: Sum of violation severity at each time point
• violation_details: Detailed information about each violation
• branch_violation_stats: Statistics for each branch with violations

Plot the time series of active load Parameters: results - Result dataset busname - Bus name case - System case timeday - Number of days bus_type - Bus type (default is "AC")

create_time_series_irradiance(irradiance_profiles, num_days=nothing)

Create time series solar irradiance data for renewable energy simulation.

Arguments

• irradiance_profiles: Matrix containing solar irradiance data, where rows represent days and columns represent hours
• num_days: Optional parameter specifying the number of days to process (defaults to all available days)

Returns

• Dictionary mapping day number to irradiance matrix for that day

Description

This function processes solar irradiance profiles and organizes them into daily irradiance matrices. For each day, it creates a matrix where each row represents a specific hour, with columns: [hour, irradiance]

The function performs the following steps:

1. Determines the total number of days available in the irradiance profiles
2. Limits processing to the specified number of days if provided
3. For each day and hour:
   • Extracts the irradiance value from the irradiance profiles
   • Creates a matrix with hour and irradiance information
4. Returns a dictionary where keys are day numbers and values are the corresponding irradiance matrices

The irradiance profiles are expected to have a structure where the first column contains date information and subsequent columns (2-25) contain hourly irradiance data.

create_time_series_loads(case::Utils.JuliaPowerCase, data, load_names, num_days)

Create time series load data for power system simulation based on input data.

Arguments

• case: Power system case data structure
• data: DataFrame containing load time series data
• load_names: Vector of load names
• num_days: Number of days to process

Returns

• Dictionary mapping day number to load matrix for that day

Description

This function processes time series load data and creates daily load matrices for power system simulation. For each day, it creates a matrix where each row represents a specific bus at a specific hour, with columns: [hour, busid, activepower, reactivepower, constzpercent, constipercent, constp_percent]

The function performs the following steps:

1. Validates that the number of time points is divisible by 24 (hours per day)
2. Filters in-service loads from the power system case
3. Maps load names to column indices in the input data
4. For each day and hour:
   • Accumulates loads connected to the same bus
   • Calculates actual active and reactive power based on apparent power and power factor
   • Computes weighted load characteristics (ZIP model parameters)
   • Ensures load characteristic percentages sum to 1
5. Returns a dictionary where keys are day numbers and values are the corresponding load matrices

The function handles cases where load names in the data match or don't match those in the power system case, maintaining power factor and appropriately scaling loads based on the input data.

create_time_series_prices(price_profiles, num_days=nothing)

Create time series price data for power system economic analysis.

Arguments

• price_profiles: Matrix containing electricity price data, where rows represent days and columns represent hours
• num_days: Optional parameter specifying the number of days to process (defaults to all available days)

Returns

• Dictionary mapping day number to price matrix for that day

Description

This function processes electricity price profiles and organizes them into daily price matrices. For each day, it creates a matrix where each row represents a specific hour, with columns: [hour, price]

The function performs the following steps:

1. Determines the total number of days available in the price profiles
2. Limits processing to the specified number of days if provided
3. For each day and hour:
   • Extracts the price value from the price profiles
   • Creates a matrix with hour and price information
4. Returns a dictionary where keys are day numbers and values are the corresponding price matrices

The price profiles are expected to have a structure where the first column contains date information and subsequent columns (2-25) contain hourly price data.

create_time_series_storage_profile(storage_profiles, num_days=nothing)

Create time series storage profile data for energy system simulation.

Arguments

• storage_profiles: Matrix containing storage profile data, where rows represent days and columns represent hours
• num_days: Optional parameter specifying the number of days to process (defaults to all available days)

Returns

• Dictionary mapping day number to storage profile matrix for that day

Description

This function processes storage profiles and organizes them into daily storage matrices. For each day, it creates a matrix where each row represents a specific hour, with columns: [hour, storage_value]

The function performs the following steps:

1. Determines the total number of days available in the storage profiles
2. Limits processing to the specified number of days if provided
3. For each day and hour:
   • Extracts the storage value from the storage profiles
   • Creates a matrix with hour and storage value information
4. Returns a dictionary where keys are day numbers and values are the corresponding storage profile matrices

The storage profiles are expected to have a structure where the first column contains date information and subsequent columns (2-25) contain hourly storage data.

extract_load_matrix_by_islands(day_load_matrix, jpc_list)

Extract and organize load data by power system islands.

Arguments

• day_load_matrix: Matrix containing load data for a day, where rows represent loads and columns include time, bus ID, and load values
• jpc_list: List of power system cases representing different islands in the network

Returns

• load_matrix_list: List of load matrices, one for each island
• isolated_load_matrix: Matrix containing load data for buses not belonging to any island

Description

This function distributes load data among different power system islands based on bus IDs. It separates the daily load data into distinct matrices for each island in the power system.

The function performs the following steps:

1. Extracts bus IDs from the load data matrix (assumed to be in the second column)
2. For each island in the power system:
   • Identifies the AC buses belonging to the island
   • Finds load data rows associated with those buses
   • Creates a load matrix specific to that island
   • If no loads are found for an island, creates an empty matrix with the same column structure
3. Identifies loads on buses that don't belong to any valid island (isolated buses)
4. Returns both the list of island-specific load matrices and the matrix for isolated loads

This function is essential for distributed power flow analysis where each island needs to be processed separately with its corresponding load data.