Add reduced basin functionality

[Wegatriespython]

This branch introduced basin filtering options to enable running nexus locally for development.

The reduced basin tool is not intended to be used for production scenarios, as the basin reduction is not a realistic phenomena. Rather it is purely intended as a tool to enable local, fast runs of nexus module intended to speed up development processes.

This helps mitigate some of the issues mentioned in #414. The reduced basin model automatically picks 1 basin per region minimum. However for feasibility it is recommend to run with all basins for South Asia.

It is not intended to be merged in its current state as there are certain PRs that this branch depends upon which need to be merged first. This draft PR is intended to serve as documentation in the intermediate period.

How to use :

The branch has cli support

Usage: mix-models water-ix nexus [OPTIONS]

  Add basin structure connected to the energy sector and water balance linking
  different water demands to supply.

Options:
  --rcps [no_climate|6p0|2p6|7p0]
                                  Specifies the climate scenario used
                                  ['no_climate','6p0','2p6']  [default:
                                  no_climate]
  --rels [low|med|high]           Specifies the reliability of hydrological
                                  data ['low','mid','high']  [default: low]
  --sdgs TEXT                     Defines if and what water SDG measures are
                                  activated
  --macro                         Defines whether the model solves with macro
  --reduced-basin / --no-reduced-basin
                                  Enable reduced basin filtering
  --filter-list TEXT              Specific basins to include (can be used
                                  multiple times)
  --num-basins INTEGER            Number of basins per region to keep when
                                  reduced-basin is enabled
  --regions [ADVANCE|B210-R11|ISR|R11|R12|R14|R17|R20|R32|RCP|ZMB]
                                  Code list to use for 'node' dimension.
  --ssp [LED|SSP1|SSP2|SSP3|SSP4|SSP5]
  --help                          Show this message and exit.

Or via script

# 1) Create a new Context and point it at your existing base‐scenario
ctx = Context()
model = "model" 
base_scen = "scen"  
ctx.handle_cli_args(url=f"ixmp://ixmp_dev/{model}/{base_scen}")

# 2) "Pass" the same CLI options that `mix‐models … water-ix` would have done
ctx.ssp = "SSP2"  # scenario_param("--ssp", default="SSP2")
regions = "R12"  # common_params("regions")

# 3) Initialize all of the MESSAGE-water bits 
water_ini(ctx, regions=regions, time=None)

ctx.nexus_set = "nexus"
ctx.RCP = "7p0"
ctx.SDG = "baseline" 
ctx.REL = "high"

# Set basin filtering to include all SAS basins
ctx.reduced_basin = True
ctx.filter_list = [
    "10|SAS",
    "115|SAS",
    "124|SAS",
    "12|SAS",
    "141|SAS",
    "148|SAS",
    "15|SAS",
    "24|SAS",
    "30|SAS",
    "50|SAS",
    "53|SAS",
    "65|SAS",
    "66|SAS",
    "67|SAS",
    "70|SAS",
]
# after water_ini…
sc_base = ctx.get_scenario()
sc_new = sc_base.clone(
    model=f"{model}",
    scenario=f"{base_scen}_{ctx.SDG}_{ctx.nexus_set}_{ctx.RCP}_{ctx.REL}",
    keep_solution=False,
)
build(ctx, sc_new)

sc_new.set_as_default()

How to review

• NA (will be filled in when its ready to be merged

PR checklist

- [ ] Continuous integration checks all ✅
- [ ] Add or expand tests; coverage checks both ✅
- [ ] Add, expand, or update documentation.
- [ ] Update doc/whatsnew.