### Configure PH options and run example

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/mpisppy/opt/ph.html

Example setup for PH options and scenario management for debugging purposes.

```python
if __name__ == "__main__":
    #==============================
    # hardwired by dlw for debugging
    import mpisppy.tests.examples.farmer as refmodel
    import mpisppy.utils.sputils as sputils

    PHopt = {}
    PHopt["asynchronousPH"] = False
    PHopt["solver_name"] = "cplex"
    PHopt["PHIterLimit"] = 5
    PHopt["defaultPHrho"] = 1
    PHopt["convthresh"] = 0.001
    PHopt["verbose"] = True
    PHopt["display_timing"] = True
    PHopt["display_progress"] = True
    # one way to set up options (never mind that this is not a MIP)
    PHopt["iter0_solver_options"]
        = sputils.option_string_to_dict("mipgap=0.01")
    # another way
    PHopt["iterk_solver_options"] = {"mipgap": 0.001}

    ScenCount = 50
    all_scenario_names = ['scen' + str(i) for i in range(ScenCount)]
    # end hardwire

    scenario_creator = refmodel.scenario_creator
    scenario_denouement = refmodel.scenario_denouement

    # now test extensions and convergers together.
    # NOTE that the options is a reference,
    #   so you could have changed PHopt instead.
    PHopt["PHIterLimit"] = 5 # the converger will probably stop it.
    PHopt["asynchronousPH"] = False
```

--------------------------------

### Install MPI on macOS (Homebrew)

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Install OpenMPI using Homebrew.

```bash
brew install open-mpi
```

--------------------------------

### Install multiple pip extras

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/install_mpi.rst.txt

Demonstrates how to install mpi-sppy with multiple optional dependencies.

```bash
pip install -e ".[mpi,doc]"
```

--------------------------------

### Progress Output Example

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/w_oscillation.rst.txt

Example of the progress line printed when the extension performs an action.

```text
[   12.34] W-oscillation interruption [iter 7]: 3 nonant(s) flagged; slammed 1 nonant(s)
```

--------------------------------

### Install MPI on Linux (Fedora/RHEL/Rocky)

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Install OpenMPI and load the module environment.

```bash
sudo dnf install openmpi openmpi-devel
# then make mpicc / mpiexec visible in this shell:
module load mpi/openmpi-x86_64
```

--------------------------------

### Install MPI on Linux (Debian/Ubuntu)

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Install OpenMPI and build essentials on Debian-based systems.

```bash
sudo apt-get update
sudo apt-get install -y libopenmpi-dev openmpi-bin build-essential
```

--------------------------------

### Solve the Farmer Example using EF

Source: https://mpi-sppy.readthedocs.io/en/latest/quick_start.html

Executes the Farmer example using the Extensive Form solver without MPI.

```bash
python -m mpisppy.generic_cylinders --module-name farmer \
    --num-scens 3 --EF --EF-solver-name gurobi
```

--------------------------------

### Command-Line Execution for W-Oscillation

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/w_oscillation.rst.txt

Example command-line arguments to pair detection and interruption configuration files.

```bash
--detect-W-oscillations examples/sizes/config/w_oscillation.json
--interrupt-W-oscillations examples/sizes/config/w_oscillation_interrupt.json
```

--------------------------------

### Install Dependencies on Ubuntu

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Install Python, git, and OpenMPI development tools within the Ubuntu shell.

```bash
sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv git \
    libopenmpi-dev openmpi-bin build-essential
```

--------------------------------

### Run mpi-sppy Example on Windows

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Execute an mpi-sppy example script using the MS-MPI mpiexec command.

```powershell
mpiexec -n 3 python -m mpi4py mpisppy\generic_cylinders.py ...
```

--------------------------------

### Create Scenario Dictionary

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/distr_data.html

Initializes a scenario for the inter-region max profit distribution example.

```python
[docs]
def region_dict_creator(scenario_name):
    """ Create a scenario for the inter-region max profit distribution example.

        The convention for node names is: 
            Symbol + number of the region (+ _ + number of the example if needed),
            with symbols DC for distribution centers, F for factory nodes, B for buyer nodes. \n
            For instance: F3_1 is the 1st factory node of region 3. \n

    Args:
        scenario_name (str):
            Name of the scenario to construct.

```

--------------------------------

### Clone and Install mpi-sppy on WSL2

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Clone the repository and perform an editable installation with MPI support.

```bash
git clone https://github.com/Pyomo/mpi-sppy.git
cd mpi-sppy
pip install -e ".[mpi]"
```

--------------------------------

### Execute Jensen's Bound Example

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/jensens.rst.txt

Run the farmer example using mpi-sppy to compute Jensen's outer bound.

```bash
mpiexec -np 3 python -m mpi4py mpisppy/generic_cylinders.py \
    --module-name farmer --num-scens 3 --default-rho 1 \
    --solver-name cplex --lagrangian --xhatshuffle \
    --lagrangian-try-jensens-first --xhatshuffle-try-jensens-first \
    --max-iterations 2
```

--------------------------------

### Setup Python Virtual Environment on WSL2

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Create and activate a virtual environment to isolate mpi-sppy dependencies.

```bash
python3 -m venv ~/mpisppy-env
source ~/mpisppy-env/bin/activate
```

--------------------------------

### Install macOS Developer Tools

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Install command-line developer tools required for building packages.

```bash
xcode-select --install
```

--------------------------------

### Solve EF and run PH

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Execute the farmer example using the extensive form or the hub-and-spoke system.

```bash
python -m mpisppy.generic_cylinders --module-name farmer \
    --num-scens 3 --EF --EF-solver-name gurobi
```

```bash
mpiexec -np 3 python -m mpi4py mpisppy/generic_cylinders.py \
    --module-name farmer --num-scens 3 \
    --solver-name gurobi_persistent --max-iterations 10 \
    --default-rho 1 --lagrangian --xhatshuffle --rel-gap 0.01
```

--------------------------------

### Install WSL2 Ubuntu Distribution

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Run this command in an administrator PowerShell to install the Ubuntu distribution for WSL2.

```powershell
wsl --install -d Ubuntu
```

--------------------------------

### Configure FWPH solver names

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/hubs.rst.txt

Example command-line configuration for using separate solvers for MIP and QP subproblems in FWPH.

```bash
--fwph-hub --solver-name glpk --fwph-qp-solver-name ipopt
```

--------------------------------

### Execute Stochastic ADMM with bundling

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/generic_admm.rst.txt

Example command to run Stochastic ADMM with bundling enabled using the --scenarios-per-bundle flag.

```bash
mpiexec -np 3 python -m mpi4py ../../mpisppy/generic_cylinders.py \
    --module-name stoch_distr --stoch-admm \
    --num-admm-subproblems 2 --num-stoch-scens 4 \
    --default-rho 10 --max-iterations 50 --solver-name cplex \
    --lagrangian --scenarios-per-bundle 4 --xhatxbar
```

--------------------------------

### Run with Xhat Input

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/xhat_from_file.rst.txt

Example execution of a generic_cylinders run utilizing an existing xhat file.

```bash
python -m mpisppy.generic_cylinders \
    --module-name my_model \
    --num-scens 10 \
    --solver-name gurobi \
    --max-iterations 50 \
    --default-rho 1.0 \
    --lagrangian --xhatshuffle \
    --xhat-from-file prior_run_xhat.npy
```

--------------------------------

### Execute Pre-Pickle Function with Command Line

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/pickling.rst.txt

Example of how to specify a pre-pickle function using the `--pre-pickle-function` command-line argument.

```bash
python -m mpisppy.generic_cylinders --module-name farmer --num-scens 12 \
    --pickle-bundles-dir farmer_pickles --scenarios-per-bundle 3 \
    --presolve-before-pickle \
    --pre-pickle-function farmer_cleanup.fix_known_vars
```

--------------------------------

### Configure W-oscillation detection

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/w_oscillation.rst.txt

Example configuration file for enabling oscillation detectors with a 20-iteration window and a 50% scenario reporting threshold.

```json
{
    "methods": {
        "w_hash_recurrence": {
            "window": 20,
            "min_frac_to_report": 0.5
        },
        "zero_crossings": {}
    },
    "output_csv": "w_oscillations.csv"
}
```

--------------------------------

### Initialize SPBase instance

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/mpisppy/spbase.html

Initialization logic for the SPBase class, including scenario creation, communicator setup, and validation checks.

```python
self._calculate_scenario_ranks()
if "bundles_per_rank" in self.options and self.options["bundles_per_rank"] > 0:
    raise RuntimeError(
        "Loose bundling (bundles_per_rank > 0) was removed in 2026.\n"
        "Use 'proper bundles' instead (--scenarios-per-bundle).\n"
        "See doc/src/properbundles.rst and mpisppy/generic_cylinders.py."
    )
self.bundling = False
self._create_scenarios(scenario_creator_kwargs)
self._look_and_leap()
self._compute_unconditional_node_probabilities()
self._attach_nlens()
self._attach_nonant_indices()
self._attach_varid_to_nonant_index()
self._create_communicators()
self._verify_nonant_lengths()
if not self.options.get("turn_off_names_check", False):
    self._verify_nonant_names()
self._set_sense()
self._use_variable_probability_setter()
self._set_solution_cache()

## SPCommunicator object
self._spcomm = None
```

--------------------------------

### Perform Initial PH Solve (Iter0)

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/mpisppy/phbase.html

Initializes solvers and executes the first PH iteration, including extension hooks and configuration setup.

```python
if (self.extensions is not None):
    self.extobject.pre_iter0()

verbose = self.options["verbose"]
dprogress = self.options["display_progress"]
dtiming = self.options["display_timing"]
dconvergence_detail = self.options["display_convergence_detail"]
smooth_type = self.options["smoothed"]
have_extensions = self.extensions is not None
have_converger = self.ph_converger is not None

def _vb(msg):
    if verbose and self.cylinder_rank == 0:
        print("(rank0)", msg)

self._PHIter = 0
self._save_original_nonants()

global_toc("Creating solvers")
self._create_solvers()

if (self.extensions is not None):
    self.extobject.iter0_post_solver_creation()

teeme = ("tee-rank0-solves" in self.options
         and self.options['tee-rank0-solves']
         and self.cylinder_rank == 0
         )
```

--------------------------------

### W-Oscillation Configuration JSON

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/w_oscillation.rst.txt

Example configuration for an interrupt file that performs slamming actions and detects oscillations.

```json
{
    "action": "slam",
    "trigger": { "start_iter": 100 },
    "slam": {
        "directives_file": "examples/sizes/config/slamming_directives.csv"
    },
    "detect": {
        "output_csv": "w_oscillations.csv",
        "methods": { "zero_crossings": {} }
    }
}
```

--------------------------------

### Verify MPI installation

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Confirm MPI and mpi4py are working with a one-sided test and a PH run.

```text
mpiexec -n 2 python -m mpi4py ../../mpi_one_sided_test.py
```

```text
mpiexec -n 3 python -m mpi4py -m mpisppy.generic_cylinders --module-name farmer --num-scens 3 --solver-name gurobi --max-iterations 5 --default-rho 1 --lagrangian --xhatshuffle
```

--------------------------------

### Execute L-Shaped algorithm

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/mpisppy/opt/lshaped.html

Main entry point to configure and run the L-Shaped method using the farmer example.

```python
def main():
    import mpisppy.tests.examples.farmer as ref
    import os
    # Turn off output from all ranks except rank 1
    if MPI.COMM_WORLD.Get_rank() != 0:
        sys.stdout = open(os.devnull, 'w')
    scenario_names = ['scen' + str(i) for i in range(3)]
    bounds = {i:-432000 for i in scenario_names}
    options = {
        "root_solver": "gurobi_persistent",
        "sp_solver": "gurobi_persistent",
        "sp_solver_options" : {"threads" : 1},
        "valid_eta_lb": bounds,
        "max_iter": 10,
   }

    ls = LShapedMethod(options, scenario_names, ref.scenario_creator)
    res = ls.lshaped_algorithm()
    if ls.cylinder_rank == 0:
        print(res)




if __name__ == '__main__':
    main()
```

--------------------------------

### Configure stochastic distribution parameters

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/stoch_distr.html

Defines configuration settings for pseudo-random scenario generation and scalable example parameters.

```python
cfg.add_to_config("spm",
                  description="mean percentage of scrap loss at the production",
                  domain=float,
                  default=5)

cfg.add_to_config("cv",
                  description="coefficient of variation of the loss at the production",
                  domain=float,
                  default=20)

cfg.add_to_config("initial_seed",
                  description="initial seed for generating the loss",
                  domain=int,
                  default=0)

### For the scalable example
cfg.add_to_config("scalable",
                  description="generate pseudo-random data parameterized by --mnpr instead of using the hardwired 2/3/4-region datasets",
                  domain=bool,
                  default=False)

cfg.add_to_config("mnpr",
                  description="max number of nodes per region and per type",
                  domain=int,
                  default=4)

cfg.add_to_config("ensure_xhat_feas",
                  description="adds slacks with high costs to ensure the feasibility of xhat yet maintaining the optimal",
                  domain=bool,
                  default=False)
```

--------------------------------

### Create a feasible xhat for the aircond example

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/feasible_xhat.rst.txt

Uses ef_xhat_nonants to generate a feasible solution for the aircond model by solving an expected-value tree proxy.

```python
import numpy as np
from mpisppy.utils.xhat_helpers import ef_xhat_nonants
from mpisppy.tests.examples.aircond import (
    scenario_creator, scenario_names_creator,
)


def feasible_xhat_creator(*, solver_name, solver_options=None,
                          branching_factors=None, **scenario_creator_kwargs):
    proxy_kwargs = dict(scenario_creator_kwargs)
    proxy_kwargs["branching_factors"] = branching_factors
    proxy_kwargs["sigma_dev"] = 0.0   # expected-value tree
    proxy_kwargs["mu_dev"] = 0.0
    proxy_kwargs.setdefault("start_seed", 0)
    snames = scenario_names_creator(int(np.prod(branching_factors)))
    return ef_xhat_nonants(
        scenario_creator, snames, solver_name=solver_name,
        scenario_creator_kwargs=proxy_kwargs, solver_options=solver_options,
    )
```

--------------------------------

### Install mpi-sppy via pip

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Install the package with MPI support from PyPI.

```bash
pip install mpi-sppy[mpi]
```

--------------------------------

### Enable Xhat from File

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/xhat_from_file.rst.txt

Use the command-line flag to specify the path to the xhat file. The format is automatically detected based on the file extension.

```bash
--xhat-from-file <path>
```

--------------------------------

### Install mpi-sppy in Editable Mode

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Install the package with MPI support enabled.

```bash
pip install -e ".[mpi]"
```

--------------------------------

### Display help for a module

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/generic_cylinders.rst.txt

Use the --help flag to see available options for a specific model module.

```bash
python -m mpisppy.generic_cylinders --module-name farmer/farmer --help
```

--------------------------------

### Initialize Solution Caches

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/mpisppy/spbase.html

Prepares the scenario data structures to store best and latest non-anticipative solutions.

```python
    def _set_solution_cache(self):
        # set up best solution cache
        for k,s in self.local_scenarios.items():
            s._mpisppy_data.best_solution_cache = None
            s._mpisppy_data.latest_nonant_solution_cache = np.full(len(s._mpisppy_data.nonant_indices), np.nan)
```

--------------------------------

### Install mpi-sppy with MPI extras

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/install_mpi.rst.txt

Installs mpi-sppy from source with mpi4py as an optional dependency.

```bash
pip install -e .[mpi]
```

--------------------------------

### Include Iteration 0 Solve in Pickle

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/pickling.rst.txt

Command-line example demonstrating the use of `--iter0-before-pickle` to include the results of the initial solve in the pickled models. It also shows how to specify different solvers for the pickling phase.

```bash
python -m mpisppy.generic_cylinders --module-name farmer --num-scens 12 \
    --pickle-bundles-dir farmer_pickles --scenarios-per-bundle 3 \
    --presolve-before-pickle --iter0-before-pickle \
    --solver-name gurobi_persistent --pickle-solver-name gurobi
```

--------------------------------

### Verify MS-MPI Installation

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Confirm that the MS-MPI runtime is correctly installed and accessible in the system PATH.

```powershell
mpiexec -help
```

--------------------------------

### Run Iteration 0 Before Pickling and Then From Pickle

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/pickling.rst.txt

This demonstrates the two-step process: first, run iteration 0 and pickle the results. Second, run subsequent jobs using the pickled iteration 0 results, skipping the initial computation.

```bash
# 1. Pay iter0 once at pickle time
python -m mpisppy.generic_cylinders --module-name farmer --num-scens 12 \
    --pickle-bundles-dir farmer_pickles --scenarios-per-bundle 3 \
    --solver-name gurobi --iter0-before-pickle
```

```bash
# 2. Every later run skips iter0 entirely
mpiexec -np 3 python -m mpi4py mpisppy/generic_cylinders.py \
    --module-name farmer --num-scens 12 \
    --unpickle-bundles-dir farmer_pickles --scenarios-per-bundle 3 \
    --solver-name gurobi --default-rho 1 --max-iterations 50 \
    --lagrangian --xhatshuffle --iter0-from-pickle
```

--------------------------------

### Test mpi4py installation

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/install_mpi.rst.txt

Runs a verification test to ensure the MPI installation is functioning correctly.

```bash
mpirun -n 2 python -m mpi4py mpi_one_sided_test.py
```

--------------------------------

### Install mpi4py via Conda

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/install_mpi.rst.txt

Installs OpenMPI and mpi4py using the conda package manager.

```bash
conda install openmpi; conda install mpi4py
```

--------------------------------

### Developer Testing Example

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/mpisppy/opt/ef.html

Example usage of the ExtensiveForm class for developer testing with the farmer problem.

```python
if __name__ == "__main__":
    # for ad hoc developer testing
    import mpisppy.tests.examples.farmer as farmer

    """ Farmer example """
    scenario_names = ["Scen" + str(i) for i in range(3)]
    scenario_creator_kwargs = {"sense": pyo.minimize, "use_integer": False}
    options = {"solver": "gurobi"}
    ef = ExtensiveForm(
        options,
        scenario_names,
        farmer.scenario_creator,
        model_name="TestEF",
        scenario_creator_kwargs=scenario_creator_kwargs,
    )
    results = ef.solve_extensive_form()
    print("Farmer objective value:", pyo.value(ef.ef.EF_Obj))
```

--------------------------------

### Enabling Stage 2 EF Solver in generic_cylinders.py

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/spokes.rst.txt

Example command-line execution of generic_cylinders.py with the --stage2-ef-solver-name flag to enable a specific solver for second-stage EF.

```bash
mpiexec -np 3 python -m mpi4py mpisppy/generic_cylinders.py \
    --module-name hydro --solver-name cplex --max-iterations 100 \
    --default-rho 1 --lagrangian --xhatshuffle --rel-gap 0.001 \
    --branching-factors "3 3" --stage2-ef-solver-name cplex
```

--------------------------------

### Install mpi4py via Conda

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Create a conda environment and install mpi4py using the conda-forge channel.

```powershell
conda create -n mpisppy-env python=3.12
conda activate mpisppy-env
conda install -c conda-forge mpi4py
```

--------------------------------

### Two-Stage Problem JSON Example

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/agnostic.rst.txt

A concrete example of the JSON structure for a two-stage problem with a single ROOT node.

```json
{
  "scenarioData": {
    "name": "unknown",
    "scenProb": 0.3333333333333333
  },
  "treeData": {
    "globalNodeCount": 1,
    "nodes": {
      "ROOT": {
        "serialNumber": 0,
        "condProb": 1.0,
        "nonAnts": [
          "NumProducedFirstStage(1)",
          "NumProducedFirstStage(2)",
          "NumProducedFirstStage(3)",
          # ...
          "NumUnitsCutFirstStage(10_10)",
        ]
      }
    }
  }
}
```

--------------------------------

### Install mpi4py via Pip

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/install_mpi.rst.txt

Installs mpi4py using pip, useful when an existing MPI version is already present.

```bash
pip install mpi4py
```

--------------------------------

### Example of Infeasible Model Constraint

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/jensens.rst.txt

An example of a model constraint that prevents the use of Jensen-style averaging due to binary variable requirements.

```python
sum(Allocation[i, j] for j in Servers) == ClientPresent[i]
```

--------------------------------

### Install mpi4py via venv and pip

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Create a virtual environment and install mpi4py using pip. Requires Microsoft C++ Build Tools and MS-MPI SDK.

```powershell
py -m venv mpisppy-env
mpisppy-env\Scripts\Activate.ps1
pip install mpi4py
```

--------------------------------

### Verify mpi-sppy installation

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/quick_start.rst.txt

Check if the package is importable and the CLI is functional.

```text
cd examples/farmer
python -m mpisppy.generic_cylinders --module-name farmer --help
```

--------------------------------

### Write first-stage solution

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/mpisppy/spbase.html

Writes the first-stage solution to a specified file, attempting to load it if not already available.

```python
def write_first_stage_solution(self, file_name,
        first_stage_solution_writer=sputils.first_stage_nonant_writer):
    """ Writes the first-stage solution, if this object reports one available.

        Args:
            file_name: path of file to write first stage solution to
            first_stage_solution_writer (optional): custom first stage solution writer function
    """

    if not self.first_stage_solution_available:
        # try loading a solution
        if not self.load_best_solution():
            raise RuntimeError("No first stage solution available")
    if self.cylinder_rank == 0:
        dirname = os.path.dirname(file_name)
        if dirname != '':
            os.makedirs(os.path.dirname(file_name), exist_ok=True)
        representative_scenario = self.local_scenarios[self.local_scenario_names[0]]
        first_stage_solution_writer(file_name, representative_scenario, self.bundling)
```

--------------------------------

### PHBase.__init__

Source: https://mpi-sppy.readthedocs.io/en/latest/_modules/mpisppy/phbase.html

Initializes the PHBase object with scenario configurations and algorithm options.

```APIDOC
## PHBase.__init__(options, all_scenario_names, scenario_creator, scenario_denouement=None, all_nodenames=None, mpicomm=None, scenario_creator_kwargs=None, extensions=None, extension_kwargs=None, ph_converger=None, rho_setter=None, variable_probability=None)

### Description
Initializes the PHBase class, which serves as the base for the Progressive Hedging algorithm implementation.

### Parameters
- **options** (dict) - Required - Options for the PH algorithm.
- **all_scenario_names** (list) - Required - List of all scenario names in the model.
- **scenario_creator** (callable) - Required - Function that takes a scenario name and returns a Pyomo Concrete model.
- **scenario_denouement** (callable) - Optional - Function for post-processing and reporting.
- **all_nodenames** (list) - Optional - List of all node names.
- **mpicomm** (MPI comm) - Optional - MPI communicator to use.
- **scenario_creator_kwargs** (dict) - Optional - Keyword arguments for scenario_creator.
- **extensions** (object) - Optional - PH extension object.
- **extension_kwargs** (dict) - Optional - Keyword arguments for extensions.
- **ph_converger** (object) - Optional - PH converger object.
- **rho_setter** (callable) - Optional - Function to set rho values.
- **variable_probability** (callable) - Optional - Function to set variable specific probabilities.
```

--------------------------------

### scenario_names_creator

Source: https://mpi-sppy.readthedocs.io/en/latest/_sources/helper_functions.rst.txt

Creates a list of scenario names based on the number of scenarios and a starting index.

```APIDOC
## scenario_names_creator(num_scens, start=0)

### Description
Creates the name of the ``num_scens`` scenarios starting from ``start``.

### Parameters
#### Arguments
- **num_scens** (int) - number of scenarios
- **start** (int) - starting index for the names

### Returns
- **list (str)** - the list of names
```