diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst index 8f49459..e77e111 100644 --- a/docs/source/quick_start.rst +++ b/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 `_ ≥ 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 `_ 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 + `_ + 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\\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 ----------------