Judgment Call modules

This module contains functions to run decentralized restoration for interdepndent networks using Judgment Call method [TDO20][TDO19], read the results, and compute comparison measures.

Running Judgment Call

dindputils.run_judgment_call(params, save_jc=True, print_cmd=True, save_jc_model=False)

Finds interdependent restoration strategies using a decentralized heuristic, Judgment Call [TDO20][TDO19].

Parameters

  • params (dict) – Global parameters, including number of iterations, judgment type, etc.

  • save_jc (bool, optional) – If true, the results are saved to files. The default is True.

  • print_cmd (bool, optional) – If true, the results are printed to console. The default is True.

  • save_jc_model (bool, optional) – If true, optimization models and their solutions are printed to file. The default is False.

Returns

None

dindputils.realized_performance(obj, t_step, functionality, judger_layer, print_cmd=False)

This function computes the realized values of flow cost, unbalanced cost, and demand deficit at the end of each step according to the what the other agent actually decides (as opposed to according to the judgment-based decisions).

Parameters

  • obj (JcModel) – Objects that contain the Judgment Call model.

  • t_step (int) – Current time step.

  • functionality (dict) – Dictionary of actual functionality state of nodes in dependee networks.

  • judger_layer (int) – Name of the layer whose agent has made the judgment.

  • print_cmd (bool, optional) – If true, the results are printed to console. The default is False.

Returns

indp_results_real – Results that represesnt the realized perforamnce of the decentralized strategy.

Return type

INDPResults

Reading results/Computing comparison measures

dindputils.read_results(combinations, optimal_combinations, cost_types, root_result_dir='../results/', deaggregate=False, rslt_dir_lyr='/agents')

This function reads the results of analyses (INDP, JC, etc.) and the corresponding objects from file and aggregates the results in a dictionary.

Parameters

  • combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the JC (or any other decentralized results) collected by generate_combinations().

  • optimal_combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the INDP (or any other optimal results) collected by generate_combinations().

  • cost_types (str) – Cost types that should be read from results and will be shown in the plots.

  • root_result_dir ('str', optional) – Root directory where the results are stored. The default is ‘../results/’.

  • deaggregate (bool, optional) – Should the de-aggregated results (for separate layers) be read. The default is False.

  • rslt_dir_lyr (str, optional) – Directory inside the root result directory where the de-aggregated results (for separate layers) are. The default is ‘/agents’.

Returns

  • cmplt_results (dict) – Dictionary that contains the read results.

  • objs (dict) – Dictionary that contains the objects corresponding to the read results.

  • .. todo:: – Games: modify the NE analysis to accommodate the case of random signal

dindputils.relative_performance(r_df, combinations, optimal_combinations, ref_method='indp', ref_jt='nan', ref_at='nan', ref_vt='nan', cost_type='Total', deaggregate=False)

This functions computes the relative performance, relative cost, and univeral relative measure [TDO20] based on results from JC and INDP.

Parameters

  • r_df (dict) – Dictionary that contains complete results by JC and INDP collected by read_results().

  • combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the JC (or any other decentralized results) collected by generate_combinations().

  • optimal_combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the INDP (or any other optimal results) collected by generate_combinations().

  • ref_method (str, optional) – Referece method to computue relative measure in comparison to. The default is ‘indp’.

  • ref_jt (str, optional) – Referece judgment type to computue relative measure in comparison to. It is used only when the reference method is JC. The default is ‘nan’.

  • ref_at (str, optional) – Referece resource allocation type to computue relative measure in comparison to. It is used only when the reference method is JC. The default is ‘nan’.

  • ref_vt (str, optional) – Referece val;uation type to computue relative measure in comparison to. It is used only when the reference method is JC, and the reference resource allocation type is Auntion. The default is ‘nan’.

  • cost_type (str, optional) – Cost type for which the relative measure is computed. The default is ‘Total’.

  • deaggregate (bool, optional) – Should the deaggregated results (for seperate layers) be computed. The default is False.

Returns

lambda_df – Dictionary that contains the relative measures.

Return type

dict

dindputils.read_resource_allocation(result_df, combinations, optimal_combinations, objs, ref_method='indp', root_result_dir='../results/')

This functions reads the resource allocation vectors by INDP and JC. Also, it computes the allocation gap between the resource allocation by JC and and the optimal allocation by INDP [TDO21b].

Parameters

  • result_df (dict) – Dictionary that contains complete results by JC and INDP collected by read_results().

  • combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the JC (or any other decentralized results) collected by generate_combinations().

  • optimal_combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the INDP (or any other optimal results) collected by generate_combinations().

  • ref_method (str, optional) – Reference method to compute relative measure in comparison to. The default is ‘indp’.

  • root_result_dir (str, optional) – Directory that contains the results. The default is ‘../results/’.

Returns

  • df_res (dict) – Dictionary that contain the resource allocation vectors.

  • df_alloc_gap (dict) – Dictionary that contain the allocation gap values.

dindputils.read_run_time(combinations, optimal_combinations, objs, root_result_dir='../results/')

This function reads the run time of computing restoration strategies by different methods.

Parameters

  • combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the JC (or any other decentralized results) collected by generate_combinations().

  • optimal_combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the INDP (or any other optimal results) collected by generate_combinations().

  • objs (dict) – Dictionary that contains the objects corresponding to the results collected by read_results().

  • root_result_dir (str, optional) – Directory that contains the results. The default is ‘../results/’.

Returns

run_time_results – Dictionary that contain run time of for all computed strategies.

Return type

dict

Other functions

dindputils.generate_combinations(database, mags, sample, layers, no_resources, decision_type, judgment_type=[''], res_alloc_type=[''], valuation_type=[''], list_high_dam_add=None, synthetic_dir=None)

This function returns all combinations of magnitude, sample, judgment type, resource allocation type, and valuation type (if applicable) involved in decentralized and centralized analyses. The returned dictionary are used by other functions to read results and calculate comparison measures.

Parameters

  • database (str) –

    Name of the initial damage database.

    options:

    For shelby county network: ‘shelby’, ‘random’, ‘ANDRES’, ‘WU’

    For synthetic networks: ‘synthetic’

  • mags (range) – Range of magnitude parameter of the current simulation.

  • sample (range) – Range of sample parameter of the current simulation.

  • layers (list) – List of layers.

  • no_resources (list) – List of number of available resources, \(R_c\).

  • decision_type (list) – List of methods.

  • judgment_type (list) – List of judgment types.

  • res_alloc_type (list) – List of resource allocation methods.

  • valuation_type (list) – List of valuation types.

  • list_high_dam_add (str, optional) – Address of the file containing the list of damage scenarios that should be read from file. It is used to read a selected subset of results. The default is None.

  • synthetic_dir (str, optional) – Address of the synthetic database files. The default is None.

Returns

  • combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the JC (or any other decentralized results).

  • optimal_combinations (dict) – All combinations of magnitude, sample, judgment type, resource allocation type involved in the INDP (or any other optimal results).

dindputils.update_progress(progress, total)

This function updates and writes a progress bar to console.

Parameters

  • progress (int) – The current progress.

  • total (int) – Total number of cases.

Returns

None.

dindputils.trapz_int(x, y)

This function computes the area underneath a curve (y) over time vector (x) including checking if the time vector is sorted.

Parameters

  • x (list) – Time vector.

  • y (list) – Vector of the integrand.

Returns

Area underneath x-y curve.

Return type

float