### Verify mpi-sppy Installation and Solver

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/quick_start.rst

Commands to navigate to the examples directory and run a specific Python script to verify the installation and solver setup. This is part of the installation verification process.

```bash
cd examples
cd farmer
python ../../mpisppy/generic_cylinders.py --module-name farmer --help
```

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

### Aircond Example Setup

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This section describes the setup for the aircond example, noting that the model file resides in a specific directory and supporting scripts are in another. It highlights the use of a Config object for parsing arguments and a create_kwargs function for processing aircond-specific arguments.

```text
The configuration data obtained by the parser are passed directly to the vanilla hub and spoke creator which knows how to use the arguments from a ``Config`` object. The arguments unique to aircond are processed by the ``create_kwargs`` function in the reference model file.
```

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

### Install ASL (Automatic Speech Recognition)

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/farmer/AMPL/install.txt

This snippet details the process of obtaining, configuring, building, and installing the ASL library from COIN-OR, a prerequisite for the Pyomo MPI-SPPY project.

```bash
$ ./get.asl
$ ./configure
$ make
$ make install
```

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

### Farmer Example Setup

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/aph.rst

Details on running the 'farmer' example, including script locations, driver scripts, model references, and MPI execution considerations for rank allocation.

```Bash
# Example driver script: AsyncPH/experiments/challenge/farmer/farmer_driver.py
# Example bash script: aph05.bash (for dispatch fraction 1/2)
# To run PH with quicky.bash

# MPI execution requires twice as many total ranks as allocated to APH
# if the only spoke is for xhat.
```

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

### Sizes Example

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This section covers the Sizes example, a two-stage problem with general integers. It mentions the 'sizes_cylinders.py' file as the usual driver and points to 'sizes_demo.py' for an example of serial execution.

```python
The file ``sizes_cylinders.py`` is the usual cylinders driver. There are other examples in the directory, such as ``sizes_demo.py``, which provides an example of serial execution (no cylinders).
```

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

### Install mpi-sppy from Source

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/quick_start.rst

Installs the mpi-sppy package in editable mode from the source repository. This is recommended for active development. It also mentions installing documentation dependencies.

```bash
pip install -e .
```

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

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

### Aircond Example Usage

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This snippet shows how to use the aircond example, specifically mentioning the 'aircond_zhat.bash' script which also calls the 'xhat4xhat' program for estimating confidence intervals.

```bash
A simple example that uses a few of the options is shown in ``aircond_zhat.bash``, which also calls the ``xhat4xhat`` program to estimate confidence intervals for the solution obtained.
```

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

### Install mpi-sppy with MPI Extras

Source: https://github.com/pyomo/mpi-sppy/blob/main/README.rst

Installs mpi-sppy from source with optional MPI support. This command should be run after cloning the repository and navigating to the root directory.

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

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

### Hydro Example without PySPModel

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This part explains the alternative approach for the Hydro example where the 'hydro.py' file is imported directly to provide the functions required by the vanilla hub and spoke creators, instead of using PySPModel.

```python
In the file ``hydro_cylinders.py`` the file ``hydro.py`` is imported because it provides the functions needed by vanilla hub and spoke creators.
```

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

### SSLp Example

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This section introduces the SSLp example as a classic two-stage problem. It mentions that the data is in PySP format and that the driver code, like 'sslp_cylinders.py', is similar to the Hydro example but simpler due to being two-stage.

```text
This is a classic problem from Ntaimo and Sen with data in PySP format so the driver code (e.g., ``sslp_cylinders.py`` that makes use of ``sslp.py``) is somewhat similar to the hydro example except sslp is simpler because it is just two stages.
```

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

### Hydro Example with PySPModel

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This section details how the Hydro example utilizes the PySPModel from mpisppy.utils.pysp_model. It shows the import statement and the instantiation of the PySPModel object, which provides necessary methods for the hub and spoke creators.

```python
from mpisppy.utils.pysp_model import PySPModel
...
hydro = PySPModel("./PySP/models/", "./PySP/nodedata/")
```

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

### StochAdmmWrapper Example Usage

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/stoch_admmWrapper.rst

Illustrates how to use StochAdmmWrapper by calling it from a driver file. The example involves a helper module for data processing and requires modifications to the driver and module files for specific problems.

```python
# Example Driver file
# The driver ``stoch_distr_admm_cylinders.py`` calls ``stoch_admmWrapper.py``,
# using the model provided by the model file (in the example ``examples.stoch_distr.stoch_distr.py``).
# Under the hood (so to speak), the file ``stoch_admmWrapper.py`` returns data structures
# (making use of so-called "variable probabilities") that can be used in the driver to create the PH
# (or APH) object which will solve the subproblems in the usual, parallel way,
# while ensuring that consensus constraints are respected as well as non-anticipativity constraints.
```

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

### UC Example with Egret and Pyomo

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This describes the UC (Unit Commitment) example, which uses the 'egret' package for the underlying unit commitment model. It also details how it reads PySP format data using the 'pyomo' dataportal and provides data files for various scenario counts.

```python
This example uses the ``egret`` package for the underlying unit commitment model and reads PySP format data using the ``pyomo`` dataportal.
```

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

### Netdes Example with Cross Scenario Cuts

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This describes the Netdes example, a challenging network design problem. It highlights the utility of cross scenario cuts and demonstrates their use in the 'netdes_cylinders.py' script.

```text
For this problem, cross scenario cuts are helpful so the use of that spoke is illustrated in ``netdes_cylinders.py``.
```

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

### Vanilla Examples: Number of Scenarios

Source: https://github.com/pyomo/mpi-sppy/blob/main/disruptions.txt

In vanilla examples, positional arguments for the number of scenarios are no longer used. The --num-scens argument is now required.

```bash
# Example for vanilla examples:
# Old: python farmer.py 100
# New: python farmer.py --num-scens 100
```

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

### Install mpi4py with Pip

Source: https://github.com/pyomo/mpi-sppy/blob/main/README.rst

Installs mpi4py using pip, which can compile against an existing MPI installation. This is useful if you already have an MPI version set up.

```bash
pip install mpi4py
```

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

### Run CCOP F with EF (Branching Factors)

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/acopf3/Readme.rst

Execute the CCOP F example using the EF (Eventual Feasibility) method by specifying branching factors. This command demonstrates how to control the test case with numerical arguments.

```bash
python ccopf_multistage.py bf1 bf2 bf3
# Example with specific branching factors:
python ccopf_multistage.py 2 3 1
```

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

### Test mpi4py Installation

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/install_mpi.rst

Tests the mpi4py installation by running a parallel test script. This command should be executed from the mpi-sppy directory.

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

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

### Run CCOP F with PH (Fixed Scenario Set)

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/acopf3/Readme.rst

Execute the CCOP F example using the PH (Progressive Hedging) method with a fixed scenario set for the upper bound. This command requires specifying the number of processors, branching factors, iterations, scenarios per bundle, and the solver.

```bash
mpiexec -np <processors> python -m mpi4py ccopf2wood.py bf1 bf2 iters scenperbund solver
# Example with specific parameters:
mpiexec -np 2 python -m mpi4py ccopf2wood.py 2 3 2 0 cplex
```

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

### CCOPF Configuration Parameters in ccopf2wood.py

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/acopf3/Readme.rst

Illustrates key parameters within the `ccopf2wood.py` file that can be modified to alter the behavior and execution of the CCOP F example. These include solver selection, problem structure, and failure probabilities.

```python
# start options
solver_name = "ipopt"
number_of_stages = 3
stage_duration_minutes = [5, 15, 30]
seed = 1134
a_line_fails_prob = 0.2
repair_fct = FixFast
# end options
```

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

### Direct API Usage Example (No Spokes)

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/drivers.rst

Illustrates using MPI-SPPy without the hub and spoke system, directly calling PH or EF, as demonstrated in the 'sizes' example.

```python
# Found in examples.sizes.sizes_demo.py
# This example also demonstrates the use of extensions.

```

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

### Simple Interactive Test

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/farmer/quartz/NOTES.txt

A basic command to run a simple interactive test on the pdebug queue using the farmer_ef.py script with specified arguments.

```bash
srun -p pdebug -N 1 -n 1 python farmer_ef.py 1 3 gurobi
```

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

### Pyomo Configuration Conversion

Source: https://github.com/pyomo/mpi-sppy/blob/main/disruptions.txt

This note highlights the conversion of Pyomo to use a configuration system, replacing 'baseparsers'. Users may need to adapt their existing setups. A bash script 'sed_config_help.bash' is provided to assist with automated edits, but manual adjustments to slurm and bash scripts will still be necessary.

```bash
# Example of a conversion step (conceptual):
# sed -i 's/baseparsers/config/g' your_script.py

# Note: Manual edits to slurm and bash scripts are still required.
```

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

### Solving with Progressive Hedging (PH)

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

Command to solve the stochastic program using Progressive Hedging with a Lagrangian spoke for lower bounds and random scenario solution fixing for upper bounds.

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

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

### Test MPI Installation

Source: https://github.com/pyomo/mpi-sppy/blob/main/README.rst

Tests the MPI installation by running a one-sided communication test script using mpi4py. This command should be executed from the mpi-sppy directory.

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

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

### Solving Extensive Form (EF)

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

Command to solve the extensive form of the farmer's stochastic program using Gurobi solver. It also shows how to extract solution data.

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

```bash
python ../../mpisppy/generic_cylinders.py --module-name farmer --num-scens 3 --EF --EF-solver-name gurobi --solution-base-name farmersol
```

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

### Solve Farmer Optimization Model

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

Solves the farmer's optimization model using the CPLEX solver and prints the optimal objective value.

```python
yields = [2.5, 3, 20]
model = build_model(yields)
solver = pyo.SolverFactory("cplex_direct")
solver.solve(model)

# Display the objective value to one decimal place
print(f"{pyo.value(model.OBJ):.1f}")
```

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

### Run Extensive Form Script

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/usar/README.md

Execute the `extensive_form.py` script. Use the `--help` option to view available command-line arguments.

```bash
python extensive_form.py --help
```

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

### L-shaped Method Convergence

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

This snippet demonstrates the output logs from the L-shaped method, showing the progression of iterations, time elapsed, and objective function values. It indicates the convergence of the method within a specified number of iterations and presents the final objective value and optimal variable assignments.

```text
Current Iteration: 2 Time Elapsed:    0.01 Time Spent on Last Master: 0.00 Time Spent Generating Last Cut Set:    0.01 Current Objective: -1296000.00
Current Iteration: 3 Time Elapsed:    0.02 Time Spent on Last Master: 0.00 Time Spent Generating Last Cut Set:    0.01 Current Objective: -160000.00
Current Iteration: 4 Time Elapsed:    0.02 Time Spent on Last Master: 0.00 Time Spent Generating Last Cut Set:    0.00 Current Objective: -113750.00
Converged in 4 iterations.
Total Time Elapsed:    0.03 Time Spent on Last Master:    0.00 Time spent verifying second stage:    0.00 Final Objective: -108390.00
good X[BEETS] 250.0
good X[CORN] 80.0
good X[WHEAT] 170.0
average X[BEETS] 250.0
average X[CORN] 80.0
average X[WHEAT] 170.0
bad X[BEETS] 250.0
bad X[CORN] 80.0
bad X[WHEAT] 170.0
```

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

### Build Farmer Optimization Model

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

Defines a Pyomo model for the farmer's optimization problem, including variables, objective function, and constraints. It takes crop yields as input.

```python
import pyomo.environ as pyo

def build_model(yields):
    model = pyo.ConcreteModel()

    # Variables
    model.X = pyo.Var(["WHEAT", "CORN", "BEETS"], within=pyo.NonNegativeReals)
    model.Y = pyo.Var(["WHEAT", "CORN"], within=pyo.NonNegativeReals)
    model.W = pyo.Var(
        ["WHEAT", "CORN", "BEETS_FAVORABLE", "BEETS_UNFAVORABLE"],
        within=pyo.NonNegativeReals,
    )

    # Objective function
    model.PLANTING_COST = 150 * model.X["WHEAT"] + 230 * model.X["CORN"] + 260 * model.X["BEETS"]
    model.PURCHASE_COST = 238 * model.Y["WHEAT"] + 210 * model.Y["CORN"]
    model.SALES_REVENUE = (
        170 * model.W["WHEAT"] + 150 * model.W["CORN"]
        + 36 * model.W["BEETS_FAVORABLE"] + 10 * model.W["BEETS_UNFAVORABLE"]
    )
    model.OBJ = pyo.Objective(
        expr=model.PLANTING_COST + model.PURCHASE_COST - model.SALES_REVENUE,
        sense=pyo.minimize
    )

    # Constraints
    model.CONSTR= pyo.ConstraintList()

    model.CONSTR.add(pyo.summation(model.X) <= 500)
    model.CONSTR.add(
        yields[0] * model.X["WHEAT"] + model.Y["WHEAT"] - model.W["WHEAT"] >= 200
    )
    model.CONSTR.add(
        yields[1] * model.X["CORN"] + model.Y["CORN"] - model.W["CORN"] >= 240
    )
    model.CONSTR.add(
        yields[2] * model.X["BEETS"] - model.W["BEETS_FAVORABLE"] - model.W["BEETS_UNFAVORABLE"] >= 0
    )
    model.W["BEETS_FAVORABLE"].setub(6000)

    return model
```

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

### Run Wheel Spinner Script (MPI)

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/usar/README.md

Execute the `wheel_spinner.py` script, intended for parallel execution using MPI. Use the `--help` option to view available command-line arguments.

```bash
mpiexec -n <num_procs> python wheel_spinner.py --help
```

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

### Basic PH Decomposition Test

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/farmer/quartz/NOTES.txt

This command initiates a basic Parallel Hybrid (PH) decomposition test using Pyomo's farmer_cylinders script. It specifies the number of nodes, tasks per node, solver, and various algorithm parameters.

```bash
srun -p pdebug -N 1 -n 6 python farmer_cylinders.py 3 --max-iterations=1000 --default-rho=1.0 --with-display-progress --solver=gurobi_persistent --bundles-per-rank=0 --no-lagrangian --no-xhatlooper --no-fwph --with-display-convergence-detail
```

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

### Hub Converger Example

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/hubs.rst

Demonstrates how to use a custom hub converger, NormRhoConverger, with mpi-sppy hubs. It shows the import statement and how to pass the converger to the hub constructor. It also mentions a command-line option to display convergence details.

```python
from mpisppy.convergers.norm_rho_converger import NormRhoConverger

# ... optionally passes NormRhoConverger to the hub constructor.
# ... using the option --with-display-convergence-detail.
```

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

### Hub and Spokes without Shared Services

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/drivers.rst

Shows how to create hub and spoke dictionaries manually without relying on the shared services in the 'examples' directory, exemplified by acopf3.ccopf2wood.py.

```python
# Example: acopf3.ccopf2wood.py
# Manually creating dictionaries like hub_dict without using vanilla.py.
# vanilla.py itself is a good reference for dictionary structures.

```

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

### Scenario Creator Function

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

Defines a function to create Pyomo models for different scenarios (good, average, bad) with associated yields. It also attaches root node information and scenario probabilities.

```python
import mpisppy.utils.sputils as sputils

def scenario_creator(scenario_name):
    if scenario_name == "good":
        yields = [3, 3.6, 24]
    elif scenario_name == "average":
        yields = [2.5, 3, 20]
    elif scenario_name == "bad":
        yields = [2, 2.4, 16]
    else:
        raise ValueError("Unrecognized scenario name")

    model = build_model(yields)
    sputils.attach_root_node(model, model.PLANTING_COST, [model.X])
    model._mpisppy_probability = 1.0 / 3
    return model
```

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

### Solving with Benders' Decomposition (L-shaped)

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/examples.rst

Python code demonstrating the use of MPI-SPPy's LShapedMethod for solving the stochastic program using Benders' decomposition. It includes setting up solver options and gathering results.

```python
from mpisppy.opt.lshaped import LShapedMethod

all_scenario_names = ["good", "average", "bad"]
bounds = {name: -432000 for name in all_scenario_names}
options = {
    "root_solver": "cplex_persistent",
    "sp_solver": "cplex_persistent",
    "sp_solver_options" : {"threads" : 1},
    "valid_eta_lb": bounds,
    "max_iter": 10,
}

ls = LShapedMethod(options, all_scenario_names, scenario_creator)
result = ls.lshaped_algorithm()

variables = ls.gather_var_values_to_rank0()
for ((scen_name, var_name), var_value) in variables.items():
    print(scen_name, var_name, var_value)
```

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

### Amalgamator Class Overview

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/amalgamator.rst

The Amalgamator class facilitates the setup and execution of a hub-and-spoke architecture. It manages the creation of hub and spoke dictionaries, utilizes sputils.spin_the_wheel, and handles solution output. Key configuration attributes include '2stage'/'mstage', 'cylinders', 'extensions', and optional 'write_solution' settings.

```python
class Amalgamator:
    # Wraps the creation and run of a simple hub-and-spokes architecture.
    # Creates hub and spokes dictionaries, calls sputils.spin_the_wheel,
    # and writes the solution to a file or a directory.
    # Requires scenario names, a scenario creator, options, and a kw_creator function.
    # cfg (Config object) must contain:
    #   - '2stage' or 'mstage': boolean indicating problem type.
    #   - 'cylinders': list of hub and spokes names.
    #   - 'extensions': list of desired extensions.
    #   - (optional) 'write_solution': dict with 'first_stage_solution' or 'tree_solution'.
    pass
```

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

### create_EF Function - mpisppy.utils.sputils

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/ef.rst

The sputils.create_EF function offers an alternative method for solving the extensive form (EF) directly. A key advantage is that its use does not require the installation of 'mpi4py'. An example of its usage can be found in 'examples.farmer.farmer_ef.py'.

```APIDOC
mpisppy.utils.sputils.create_EF(*args, **kwargs)
  Creates the extensive form (EF) for optimization under uncertainty.
  This function does not require the installation of 'mpi4py'.

  Arguments:
    (Details of arguments would be listed here if available in the source documentation)

  Example:
    Illustrated in examples.farmer.farmer_ef.py
```

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

### Install mpi4py using Conda

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/install_mpi.rst

Installs OpenMPI and mpi4py using conda. It is recommended to install OpenMPI first, followed by mpi4py.

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

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

### Install gamspy_base and gamsapi

Source: https://github.com/pyomo/mpi-sppy/blob/main/examples/farmer/GAMS/installation.txt

Installs the gamspy_base and gamsapi Python packages using pip. These are essential dependencies for using Pyomo with GAMS and MPI.

```bash
pip install gamspy_base gamsapi
```

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

### Install mpi-sppy with mpi4py Extras

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/install_mpi.rst

Installs mpi-sppy from pip or source with mpi4py as an optional dependency. This is done by adding the `[mpi]` extras flag.

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

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

### Install mpi4py using Pip

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/install_mpi.rst

Installs mpi4py using pip. This method is suitable if you have an existing version of MPI and want to compile mpi4py against it.

```bash
pip install mpi4py
```

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

### Install mpi4py with Conda

Source: https://github.com/pyomo/mpi-sppy/blob/main/README.rst

Installs OpenMPI and mpi4py using conda. This is a recommended method for non-HPC platforms.

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

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

### APH Options Table

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/aph.rst

Lists the configurable options for the APH algorithm, mapping paper parameters to software options and parser arguments. Includes descriptions for each option.

```APIDOC
APH Options:

- PHIterLimit: A termination criterion.
- defaultPHrho: Proximal term multiplier in objective and y update.
- APHnu: Step size multiplier (e.g. 0.5; default 1).
- APHgamma: Primal vs. dual emphasis (0,2) default 1; larger is primal.
- dispatch_frac: Fraction of subproblems at each rank to dispatch.
- async_frac_needed: Fraction of ranks to wait for (default 1).
- async_sleep_secs: The software hangs if too small (default 0.5).
- APHuse_lag: In step 7,8 use w and z from last solve for i.
```

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

### SPBase API Documentation

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/output_solutions.rst

Provides details on the `write_tree_solution` method within the `mpisppy.spbase.SPBase` class, used for outputting solution trees and first-stage solutions.

```APIDOC
SPBase:
  write_tree_solution(directory_name: str, writer_func: callable = None)
    Outputs the entire solution tree to the specified directory.
    Parameters:
      directory_name: The name of the directory to write the solution tree.
      writer_func: An optional customized writer function.

  write_tree_solution(file_name: str, writer_func: callable = None)
    Outputs the first stage solution to the specified file.
    Parameters:
      file_name: The name of the file to write the first stage solution.
      writer_func: An optional customized writer function.
```

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

### Vanilla Configuration Update

Source: https://github.com/pyomo/mpi-sppy/blob/main/disruptions.txt

When using 'vanilla', the first element in 'beans' should now be 'cfg' of type Config, replacing the previous use of 'args'.

```python
# Conceptual change in vanilla examples:
# Old:
# beans = [args, ...]

# New:
# from pyomo.common.config import Config
# cfg = Config()
# # ... configure cfg ...
# beans = [cfg, ...]
```

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

### Scenario Creator Function Logic

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/agnostic.rst

Describes the conditional logic for scenario creator functions based on scenario naming conventions. If a scenario name starts with 'scen', it returns a single scenario. If it starts with 'bundle', it returns an extensive formulation for a group of scenarios.

```python
def scenario_creator(scenario_name, **kwargs):
    if scenario_name.startswith('scen'):
        # Return a single scenario
        pass
    elif scenario_name.startswith('bundle'):
        # Return a bundle (extensive formulation)
        pass
```

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

### kw_creator Function

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/helper_functions.rst

Creates a dictionary of keyword arguments used in the scenario_creator function. It takes a configuration object as input.

```Python
def kw_creator(cfg):
    """Creates a dictionary of keyword arguments for scenario_creator.

    Args:
        cfg (config object): specifications for the problem

    Returns:
        dict (str): the dictionary of key word arguments that is used in ``scenario_creator``
    """
    pass
```

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

### Extending Scenario Creator Arguments

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/drivers.rst

Demonstrates how to pass custom arguments to the scenario creator via scenario_creator_kwargs, as shown in examples like farmer_cylinders.py.

```python
# Example: Adding a '--crops-mult' argument passed to the scenario creator.
# scenario_creator_kwargs['crops_mult'] = args.crops_mult

```

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

### Tight Integration: Model and Wrapper Files

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/agnostic.rst

Describes the two essential files a modeler needs to supply for tight integration: the model file in the guest AML and a thin Python wrapper.

```python
# Example: farmer.mod (AMPL model file)
# ... model definition ...

# Example: farmer_ampl_model.py (Python wrapper)
# from pyomo.environ import * # Or relevant imports
# from mpisppy.utils import config

# def create_farmer_model(scenario_name):
#     # Load the AMPL model
#     # Modify stochastic parameters based on scenario_name
#     # Return the Pyomo model object
#     pass

# def scenario_creator(scenario_name):
#     model = create_farmer_model(scenario_name)
#     return model
```

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

### scenario_names_creator Function

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/helper_functions.rst

Generates a list of scenario names. It takes the desired number of scenarios and an optional starting index as input.

```Python
def scenario_names_creator(num_scens, start=0):
    """Creates the name of the ``num_scens`` scenarios starting from ``start``

    Args:
        num_scens (int): number of scenarios
        start (int): starting index for the names

    Returns:
        list (str): the list of names
    """
    pass
```

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

### Amalgamator Solution Output Options

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/output_solutions.rst

Specifies file and directory names for outputting first-stage and tree solutions when using the Amalgamator.

```python
options['write_solution'] = {
    'first_stage_solution': 'amalgamator_first_stage.txt',
    'tree_solution': 'amalgamator_tree_sol'
}
```

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

### Command Line Argument Parsing

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/stoch_admmWrapper.rst

Parses arguments from the command line and adds them to a configuration object. Some arguments are mandatory. Additional arguments like `cfg.run_async` and cylinder creation methods need to be called later in the driver.

```APIDOC
py:function:: _parse_args()
    :no-index:

    Gets argument from the command line and add them to a config argument. Some arguments are required.

    Note:
        Some arguments, such as ``cfg.run_async`` and all the methods creating new cylinders
        not only need to be added in the ``_parse_args()`` method, but also need to be called later in the driver.
```

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

### Set Initial Proximal Cut Count

Source: https://github.com/pyomo/mpi-sppy/blob/main/doc/src/secretmenu.rst

The `initial_proximal_cut_count` option controls the initial number of cuts when `linearize_proximal_terms` is enabled. The default value is 2. This example shows how to set it to 4.

```python
hub_dict["opt_kwargs"]["PHoptions"]["initial_proximal_cut_count"] = 4
```