Add Quick MATLAB Example section to quick_start.rst

docs/source/quick_start.rst

@@ -2,7 +2,8 @@ Quick Start
 ***********
 
 This guide walks through the bare essentials: installing CEA, running the
-command-line solver on the supplied sample problems, and calling the Python API.
+command-line solver on the supplied sample problems, and calling the Python
+and MATLAB APIs.
 
 Prerequisites
 -------------
@@ -11,6 +12,10 @@ Prerequisites
   Intel ``ifort`` 2021+).
 * `CMake <https://cmake.org>`_ ≥ 3.19 and a build tool (Ninja or Make).
 * Python ≥ 3.11 if you plan to use the Python binding.
+* MATLAB, if you plan to use the MATLAB binding — no prior Python
+  experience needed. The Quick MATLAB Example below walks through
+  everything, including installing Python itself if you don't already have
+  a copy.
 
 Installation
 ------------
@@ -109,6 +114,107 @@ The ``EqSolver`` and its siblings ``RocketSolver``, ``ShockSolver``, and
 ``DetonationSolver`` expose the same properties as the Fortran core.  See
 :doc:`interfaces/python_api` for the full API reference.
 
+Quick MATLAB Example
+--------------------
+
+CEA doesn't ship a native MATLAB toolbox. Instead, MATLAB calls CEA through
+a small bridge to Python, using MATLAB's built-in ``pyenv`` feature. You
+don't need to know any Python to use it — follow the steps below once, then
+the two commands under "Every MATLAB Session" are all you'll retype.
+
+If you already have a working Python installation with ``cea`` installed,
+skip to "Every MATLAB Session" below.
+
+One-Time Setup
+~~~~~~~~~~~~~~
+
+1. Install Python, if you don't already have it. Download the Windows
+   installer for Python 3.12 from
+   `python.org <https://www.python.org/downloads/>`_ and run it. On the
+   first installer screen, check **"Add python.exe to PATH"** before
+   clicking "Install Now" — this lets you type ``python`` in a Command
+   Prompt window. (Python 3.12 is used here because it works with every
+   current MATLAB release; if MATLAB later refuses to load it, see the
+   troubleshooting note at the end of this step.)
+
+2. Open a Command Prompt window — a plain text window for typing commands,
+   separate from MATLAB. Click the Start menu (or press the Windows key),
+   type ``cmd``, and press Enter, or click "Command Prompt" in the search
+   results. If you had a Command Prompt window open before you installed
+   Python, close it and open a new one — it won't see the update otherwise.
+   Then install ``cea``::
+
+       python -m pip install cea
+
+   This downloads a ready-to-use package — no compiler, no conda, nothing
+   else to build.
+
+   *Troubleshooting:* if MATLAB later reports that this Python version
+   isn't supported, your MATLAB release may need an older or newer Python
+   than 3.12. Check MathWorks' `Python compatibility table
+   <https://www.mathworks.com/support/requirements/python-compatibility.html>`_
+   for your release, install that version from python.org instead (same
+   steps as above), and run ``python -m pip install cea`` again using that
+   version.
+
+3. In the same Command Prompt window, find the full path to the Python you
+   just installed — you'll paste it into MATLAB below::
+
+       where python
+
+   This prints one or more paths ending in ``python.exe``; copy the one
+   under the Python version you just installed (e.g.
+   ``C:\Users\<you>\AppData\Local\Programs\Python\Python312\python.exe``).
+
+Every MATLAB Session
+~~~~~~~~~~~~~~~~~~~~
+
+Paste these lines into the MATLAB Command Window, using the path from step 3
+above, before doing anything else with ``cea``::
+
+    pyenv('Version', 'C:\path\to\python.exe');
+
+    cea = py.importlib.import_module('cea');
+    ceam = py.importlib.import_module('cea.matlab');
+
+This only needs to run once per MATLAB session — running ``pyenv`` a second
+time after these lines have already run will error, so if you need to
+change the Python path, restart MATLAB first.
+
+*Tip:* save these three lines as a MATLAB script, e.g. ``setup_cea.m``, so
+each session you just type ``setup_cea`` instead of retyping them.
+
+Solving a Problem
+~~~~~~~~~~~~~~~~~
+
+With the session set up, solve a stoichiometric H\ :sub:`2`/O\ :sub:`2`
+constant-enthalpy, constant-pressure (HP) combustion problem — the
+adiabatic flame temperature of hydrogen burning in oxygen::
+
+    reactants = py.list({'H2', 'O2'});
+    pressure = cea.units.atm_to_bar(1.0);
+
+    solution = ceam.eq_solve(cea.HP, reactants, ...
+        fuel_amounts=py.numpy.array([2.0, 0.0]), ...
+        oxid_amounts=py.numpy.array([0.0, 1.0]), ...
+        moles=true, ...
+        T_reac=298.15, ...
+        P=pressure);
+
+    fprintf('Adiabatic flame temperature: %.1f K\n', solution.T);
+
+This should print ``Adiabatic flame temperature: 3074.5 K``.
+``fuel_amounts`` and ``oxid_amounts`` each list one amount per entry in
+``reactants``: ``[2.0, 0.0]`` is 2 mol of ``H2`` and 0 mol of ``O2`` on the
+fuel side, ``[0.0, 1.0]`` is 0 mol ``H2`` and 1 mol ``O2`` on the oxidizer
+side — together, 2 mol H2 to 1 mol O2.
+
+``solution`` holds the result as plain numbers and arrays you can read
+directly with dot notation, the same as any other MATLAB struct — no
+further conversion needed. ``solution.T`` above is the temperature in K;
+see :doc:`interfaces/matlab_api` for the full list of result fields and the
+other three solver functions (rocket, shock, and detonation problems).
+
 Reporting Issues
 ----------------