{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "dfeaa8fc",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-10-02T14:44:22.434526Z",
     "iopub.status.busy": "2026-10-02T14:44:22.434247Z",
     "iopub.status.idle": "2026-10-02T14:44:22.440294Z",
     "shell.execute_reply": "2026-10-02T14:44:22.439481Z"
    },
    "papermill": {
     "duration": 0.009052,
     "end_time": "2026-10-02T14:44:22.441084+00:00",
     "exception": false,
     "start_time": "2026-10-02T14:44:22.432032+00:00",
     "status": "completed"
    },
    "tags": [
     "remove-input",
     "active-ipynb",
     "remove-output"
    ]
   },
   "outputs": [],
   "source": [
    "try:\n",
    "    from openmdao.utils.notebook_utils import notebook_mode  # noqa: F401\n",
    "except ImportError:\n",
    "    !python -m pip install openmdao[notebooks]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b41f86e1",
   "metadata": {
    "papermill": {
     "duration": 0.000909,
     "end_time": "2026-10-02T14:44:22.462234+00:00",
     "exception": false,
     "start_time": "2026-10-02T14:44:22.461325+00:00",
     "status": "completed"
    },
    "tags": []
   },
   "source": [
    "(features:debugging:controlling_mpi)=\n",
    "# Controlling MPI Detection\n",
    "\n",
    "By default, OpenMDAO will attempt to import the mpi4py module. If that fails, or if `MPI.COMM_WORLD.size` is 1, execution continues normally without MPI support.\n",
    "\n",
    "Continuing can be problematic if MPI processing was intended, so this behavior can be modified by setting the environment variable `OPENMDAO_USE_MPI`:\n",
    "\n",
    "  - A value of `True` (or `Yes`, `1`, or `Always`; case-insensitive) will raise an exception if mpi4py fails to load. If successful, MPI will be used even if `MPI.COMM_WORLD.size` is only `1`.\n",
    "  - Any other value will prevent loading of the mpi4py module, disabling MPI usage. This can be useful when:\n",
    "    - MPI is disallowed (e.g. certain HPC cluster head nodes)\n",
    "    - Loading mpi4py causes unacceptable overhead\n",
    "    - Displaying the warning message is undesirable\n",
    "\n",
    "# MPI Troubleshooting\n",
    "\n",
    "This section describes how to fix certain MPI related problems.\n",
    "\n",
    "The following errors may occur when using certain versions of Open MPI:\n",
    "\n",
    "Fix the **There are not enough slots available in the system…** error by defining\n",
    "\n",
    "    OMPI_MCA_rmaps_base_oversubscribe=1\n",
    "\n",
    "in your environment.\n",
    "\n",
    "Fix the **A system call failed during shared memory initialization that should not have…** error by setting\n",
    "\n",
    "    OMPI_MCA_btl=self,tcp\n",
    "\n",
    "in your environment.\n",
    "\n",
    "# MPI Testing\n",
    "\n",
    "Running OpenMDAO’s MPI tests requires the use of the [testflo](https://github.com/OpenMDAO/testflo) package. You must have a working MPI library installed, for example *openmpi* or *MVAPICH*, and the *mpi4py*, and *petsc4py* python packages must be installed in your python environment.\n",
    "\n",
    "Also, note that you can redirect the output from each MPI rank to a separate file by setting the `USE_PROC_FILES` [environment variable](../../other_useful_docs/environment_vars.ipynb)."
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Tags",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.14"
  },
  "orphan": true,
  "papermill": {
   "default_parameters": {},
   "duration": 0.955889,
   "end_time": "2026-10-02T14:44:22.741749+00:00",
   "environment_variables": {},
   "exception": null,
   "input_path": "/home/runner/work/OpenMDAO/OpenMDAO/openmdao/docs/openmdao_book/features/debugging/controlling_mpi.ipynb",
   "output_path": "/home/runner/work/OpenMDAO/OpenMDAO/openmdao/docs/_executed_book/features/debugging/controlling_mpi.ipynb",
   "parameters": {},
   "start_time": "2026-10-02T14:44:21.785860+00:00",
   "version": "2.7.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}