API Reference

This section provides API documentation for OSeMOSYS-RDM’s Python modules.

Note

This API reference is auto-generated from docstrings. For more detailed usage, see the User Guide.

Core Modules

z_auxiliar_code

The main utility module containing core functions.

src.workflow.z_auxiliar_code.obtain_structure_file(scenario_file, output_file, structure_file, num_timeslices)

Extract model structure from a scenario file.

Parameters:

  • scenario_file – Path to the OSeMOSYS scenario file

  • output_file – Path for the output Excel file

  • structure_file – Path to the OSeMOSYS structure reference

  • num_timeslices – Number of time slices in the model

Returns:

Dictionary of sets

src.workflow.z_auxiliar_code.isolate_params(scenario_file)

Parse a scenario file and isolate parameters.

Parameters:

scenario_file – Path to the scenario file

Returns:

Tuple of (data_per_param dict, special_sets list)

src.workflow.z_auxiliar_code.generate_df_per_param(scenario_name, data_per_param, num_timeslices)

Generate DataFrames for each parameter.

Parameters:

  • scenario_name – Name of the scenario

  • data_per_param – Dictionary of parameter data

  • num_timeslices – Number of time slices

Returns:

Tuple of (list_dataframes, dict_dataframes, parameters_without_values)

src.workflow.z_auxiliar_code.run_osemosys(solver, output_dir, data_file, model_file, output_base)

Execute OSeMOSYS optimization.

Parameters:

  • solver – Solver name (‘glpk’, ‘cbc’, ‘cplex’, ‘gurobi’)

  • output_dir – Directory for output files

  • data_file – Path to data file

  • model_file – Path to model formulation

  • output_base – Base name for output files

src.workflow.z_auxiliar_code.data_processor_new(sol_file, structure_file, scenario, future, solver, params_to_print, output_format)

Process solver output into standardized format.

Parameters:

  • sol_file – Path to solution file

  • structure_file – Path to model structure file

  • scenario – Scenario name

  • future – Future ID

  • solver – Solver used

  • params_to_print – DataFrame of parameters to export

  • output_format – ‘csv’ or ‘parquet’

Interpolation Functions

src.workflow.z_auxiliar_code.interpolation_non_linear_final(time_list, value_list, multiplier, last_year, initial_year)

Non-linear interpolation to a modified final value. Rescales each annual delta by m_new/m_original. For flat baselines (|m_original| < 1e-9) the function applies a small damped per-year increment to avoid the spurious linear ramp the original implementation produced.

Parameters:

  • time_list – List of years

  • value_list – List of base values

  • multiplier – Final value multiplier

  • last_year – Last year of analysis

  • initial_year – Year uncertainty begins

Returns:

List of new values

src.workflow.z_auxiliar_code.interpolation_multiplicative_final(time_list, value_list, final_multiplier, finyear, initial_year)

Shape-preserving perturbation. Multiplies each baseline point by a year- dependent ramp that grows linearly from 1.0 at initial_year to final_multiplier at finyear (clamped to 1.0 before initial_year and to final_multiplier after finyear). Codos, plateaus, and other inflections in the baseline are preserved by construction because only the magnitude is rescaled.

Parameters:

  • time_list – List of years

  • value_list – List of base values

  • final_multiplier – Multiplier applied at finyear

  • finyear – Last year of analysis

  • initial_year – Year uncertainty begins (multiplier is 1.0 here)

Returns:

List of new values

src.workflow.z_auxiliar_code.interpolation_constant_trajectory(time_list, value_list, initial_year)

Maintain constant trajectory from initial year.

Parameters:

  • time_list – List of years

  • value_list – List of base values

  • initial_year – Year to freeze values

Returns:

List of constant values

src.workflow.z_auxiliar_code.interpolation_linear(time_list, value_list, multiplier, last_year, initial_year)

Linear interpolation to modified final value.

Parameters:

  • time_list – List of years

  • value_list – List of base values

  • multiplier – Final value multiplier

  • last_year – Last year of analysis

  • initial_year – Year uncertainty begins

Returns:

List of linearly interpolated values

src.workflow.z_auxiliar_code.interpolation_logistic_trajectory(time_list, value_list, multiplier, last_year, initial_year)

Logistic (S-curve) trajectory interpolation.

Parameters:

  • time_list – List of years

  • value_list – List of base values

  • multiplier – Final value multiplier

  • last_year – Last year of analysis

  • initial_year – Year uncertainty begins

Returns:

List of values following logistic curve

Pipeline Scripts

run.py

Main pipeline orchestrator.

run.main()[source]

Main entry point for the OSeMOSYS-RDM pipeline.

Command line arguments:

  • module: ‘rdm’, ‘prim’, or ‘all’

  • --force: Force re-execution

  • --skip-pull: Skip DVC pull

  • --env-name: Custom environment name

  • --env-file: Path to environment.yaml

run.run_rdm_pipeline(env_name, force, skip_pull)[source]

Execute the RDM pipeline stages.

Parameters:

  • env_name – Conda environment name

  • force – Force re-execution of all stages

  • skip_pull – Skip DVC pull operation

run.run_prim_pipeline(env_name, force, skip_pull)[source]

Execute the PRIM analysis pipeline.

Parameters:

  • env_name – Conda environment name

  • force – Force re-execution of all stages

  • skip_pull – Skip DVC pull operation

DVC Wrapper Scripts

scripts.run_base_future.main()

Execute base future scenario (Future 0).

Temporarily modifies Interface_RDM.xlsx to run only the base case, then restores the original configuration.

scripts.run_rdm_experiment.main()

Execute RDM experiment with multiple futures.

Configures for RDM-only execution and runs the experiment manager.

scripts.run_postprocess.main()[source]

Aggregate and concatenate results from all futures.

Calls the output dataset creator to consolidate parquet files.

scripts.run_prim_files_creator.main()[source]

Create PRIM input files from RDM results.

Executes t3f1_prim_structure.py and t3f2_prim_files_creator.py.

scripts.run_prim_analysis.main()[source]

Execute PRIM scenario discovery analysis.

Runs t3f3_prim_manager.py and t3f4_range_finder_mapping.py.

PRIM Module

t3f2_prim_files_creator

src.workflow.4_PRIM.t3f2_prim_files_creator.f1_create_prim_files(dir_elements, dirl, scen, dict_pfcp, analysis_list, dict_set_matching, period_control, all_exp_data, exp_id, params, dicPop)

Create PRIM-ready files from experiment data.

Parameters:

  • dir_elements – List of files in directory

  • dirl – Directory path

  • scen – Scenario name

  • dict_pfcp – PRIM files creator parallel config

  • analysis_list – List of analysis IDs

  • dict_set_matching – Set matching dictionary

  • period_control – Period configuration

  • all_exp_data – All experiment data

  • exp_id – Experiment ID

  • params – YAML parameters

  • dicPop – Population dictionary

src.workflow.4_PRIM.t3f2_prim_files_creator.f2_exe_postproc(prim_tbl, prim_tbl_bau, period_list, yr_ini_list, yr_fin_list, list_acc_files, list_dfs, actor, name, set_type, source, col_name, col_sets, den_frml, mcod, num_frml, last_indicate, prms, set_argmnt, sup_sets, vmng, exp_data, future, scen, whole_period, df_sm, tbl_id, o_or_d, ana_ID, exp_id, params, dicPop)

Execute post-processing for PRIM table creation.

Parameters:

  • prim_tbl – PRIM table dictionary

  • prim_tbl_bau – BAU reference table

  • period_list – List of periods

  • ... – Additional parameters

Returns:

Updated PRIM table

Data Structures

Experiment Dictionary

experiment_dictionary = {
    1: {  # X_Num
        'Category': str,           # Uncertainty category
        'Math_Type': str,          # Mathematical type
        'Exact_X': str,            # Description
        'Involved_Scenarios': list,
        'Involved_First_Sets_in_Osemosys': list,
        'Involved_Second_Sets_in_Osemosys': list,
        'Involved_Third_Sets_in_Osemosys': list,
        'Exact_Parameters_Involved_in_Osemosys': list,
        'Initial_Year_of_Uncertainty': int,
        'Explored_Parameter_of_X': str,
        'Futures': list,           # [1, 2, 3, ..., N]
        'Values': list,            # Sampled values per future
    },
    # ...
}

Inherited Scenarios

inherited_scenarios = {
    'Scenario1': {
        1: {  # Future ID
            'CapitalCost': {
                'r': [],      # Region
                't': [],      # Technology
                'y': [],      # Year
                'value': [],  # Values
            },
            # ... other parameters
        },
        # ... other futures
    },
    # ... other scenarios
}

PRIM Files Dictionary

pfd = {
    'o': {  # Outcomes
        1: {  # Table ID
            'period_name': {
                'column_name': {
                    'vl': [],    # Values list
                    'snl': [],   # Store num lists
                },
                'Fut_ID': [],
                'Scenario': [],
            },
        },
    },
    'd': {  # Drivers
        # Same structure as outcomes
    },
}