.. quickstart QuickStart ========== .. note:: RocketCEA on Windows has become much easier for versions 1.2.0 and above. In fact, in most situations, Windows users can skip the step of installing MinGW gfortran and simply install a pre-compiled binary wheel for python 3.7 through 3.12. The deprecation of numpy.distutils forced a FORTRAN build conversion to `meson `_ that has turned out to be a nice improvement. (Many thanks to `joel-martin `_ for critical help with that conversion.) Install Numpy & Matplotlib -------------------------- When installing RocketCEA from source code or from a `PyPI sdist `_, RocketCEA depends on `f2py `_ to compile the FORTRAN `NASA CEA code `_ and `f2py `_ is part of `numpy `_. After compilation, `numpy `_ will needed to interface with the compiled code. RocketCEA also makes use of the `matplotlib `_ package for creating plots. An optional package for some advanced features is `scipy `_. To install `numpy `_, `matplotlib `_ and `scipy `_, give the commands:: pip install numpy matplotlib scipy OR perhaps... pip install --upgrade numpy pip install --upgrade matplotlib pip install --upgrade scipy Some Linux systems may require:: sudo pip install numpy matplotlib scipy OR perhaps... sudo pip3 install numpy matplotlib scipy Install Compiler ---------------- .. note:: Windows users can skip "Install Compiler" and go to :ref:`link_install_rocketcea` Using `f2py `_ to compile FORTRAN requires a FORTRAN compiler. I recommend using `gfortran `_ on all platforms so that there are no FORTRAN incompatibilities between platforms. Each operating system has its own approach to install `gfortran `_ Click: :ref:`link_installgfortran` to see install instructions for a few platforms that I have tested. .. _link_install_rocketcea: Install RocketCEA ----------------- **After** the above installs have been accomplished, the easiest way to install RocketCEA is:: pip install rocketcea OR perhaps pip install --prefer-binary rocketcea OR on Linux sudo pip install rocketcea sudo pip3 install rocketcea OR perhaps pip install --user rocketcea pip3 install --user rocketcea Try a quick test of the install by pasting the following into a command terminal:: python -c "from rocketcea.cea_obj import CEA_Obj; C=CEA_Obj(oxName='LOX', fuelName='LH2'); print(C.get_Isp())" should result in: 374.30361765576265 .. _link_windows_bat_file: Windows Batch File ------------------ **For versions of RocketCEA 1.2.0 and above** While the above section should work for Windows binary wheel installs, it is now much easier to install from source code as well. It will be necessary to :ref:`link_installgfortran`, however, once FORTRAN is available, the steps to compile and install RocketCEA are virtually identical to installing binary wheels. .. code-block:: batch REM =============== Install RocketCEA from Source Code ================ REM make sure that gfortran is in PATH set PATH=C:\MinGW\mingw64\bin;C:\MinGW\mingw64\lib;%PATH% REM **OPTIONALLY** install some dependencies pip install numpy matplotlib scipy REM install source downloaded from PyPI (e.g. rocketcea-1.2.0.tar.gz OR uncompressed source) pip install rocketcea-1.2.0.tar.gz ... OR ... pip install . REM Test the compiled module python -c "from rocketcea.cea_obj import CEA_Obj; C=CEA_Obj(oxName='LOX', fuelName='LH2'); print(C.get_Isp())" python -c "from rocketcea.cea_obj import __version__; print( 'RocketCEA Version:', __version__)" Old Windows Batch File ---------------------- .. note:: 3/23/2024: Ignore the following batch file for RocketCEA versions 1.2.0 and above. .. note:: 3/14/2024: The deprecation of numpy.distutils has made Windows installs much more problematic. In order to support deprecated features in pip and numpy, we need to use old versions of these packages. For this reason, you may want to install RocketCEA in a `virtual environment `_ rather than your primary installation. Further, until `meson `_ is implemented, RocketCEA only officially supports python 3.7 thru 3.11 on Windows. .. note:: for `Anaconda `_ on Windows, see "Anaconda Windows Batch File" section below. RocketCEA on Windows can be problematic. Often the problem is in the PATH environment variable where the wrong files are found for the intended install, and even more often it is because the proper compiler build tools are not available. The Windows batch file below addresses both of those problems. Remember that the FORTRAN compiler must also be installed (see: :ref:`Install MinGW on Windows 10 `) Notice that the batch file makes the PATH as simple as possible so that only the 64 bit MinGW files and desired python files are found. Note that the batch file assumes that python 3.9 64 bit is the python version installed at **C:\\Python39_64** and that MinGW 64 bit is installed at **C:\\MinGW\\mingw64\\bin** and **C:\\MinGW\\mingw64\\lib**. *Edit those path names for your situation.* The batch file starts by uninstalling rocketcea in case bad files are left from previous attempts. (This would not be necessary in a fresh virtual environment.) Finally, note that the batch file installs RocketCEA version 1.1.34 which is `likely` the last version to depend on numpy.distutils. **You may need to edit the hard-coded paths to your own location of python and MinGW.** - Copy and paste the batch file code below into an editor - Edit the hard-coded paths to your own location of python and MinGW (i.e. perhaps change C:\\Python39_64 and C:\\MinGW\\mingw64) - Save the edited BAT file (e.g. as RUN_SETUP_BUILD_WIN64.BAT) - Open a command prompt terminal and navigate to the BAT file directory. - Give the command RUN_SETUP_BUILD_WIN64.BAT .. note:: 3/14/2024: BAT File successful on Windows 11 virtual environments with 64 bit python 3.7 thru 3.11 The virtual environments had the **parent** python version's subdirectories "libs" and "include" copied into them. .. code-block:: batch rem =============== RUN_SETUP_BUILD_WIN64.BAT ================ rem Make sure that PATH is as simple as possible SET "MYPYTHONPATH=C:\Python39_64" set PATH=C:\MinGW\mingw64\bin;C:\MinGW\mingw64\lib;%MYPYTHONPATH%;%MYPYTHONPATH%\Scripts rem OR perhaps simply... set PATH=C:\MinGW\mingw64\bin;C:\MinGW\mingw64\lib;%PATH% REM The trick for installing RocketCEA on Windows seems to be REM pre-installing the dependency packages (e.g. numpy, scipy and matplotlib) REM so that the pip option (--global-option) for rocketcea only applies to rocketcea. rem pip 24.2 will enforce --global-option deprecation rem ... so use an older pip python -m pip install pip==23.3.2 rem future is removed after rocketcea 1.1.34 pip install future pip install build pip install wheel==0.38.4 rem in case of an earlier failed attempt to install rocketcea pip uninstall -y rocketcea rem setuptools.find_packages is used. rem for python 3.7 use: pip install setuptools==59.8.0 pip install setuptools==69.1.1 pip install numpy<=1.26.4 rem pip install numpy==1.25.2 pip install pillow pip install matplotlib pip install scipy rem pip install rocketcea, but with global options. pip install --global-option build_ext --global-option --compiler=mingw32 rocketcea==1.1.34 rem Test the compiled module python -c "from rocketcea.cea_obj import CEA_Obj; C=CEA_Obj(oxName='LOX', fuelName='LH2'); print(C.get_Isp())" python -c "from rocketcea.cea_obj import __version__; print( 'RocketCEA Version:', __version__)" .. note:: The "trick" for installing RocketCEA on Windows seems to be pre-installing the dependency packages (e.g. numpy, scipy and matplotlib) so that the pip options for rocketcea only apply to rocketcea. If you are having trouble on Windows, you may want to try :ref:`link_windows_wsl` Anaconda Windows Batch File --------------------------- .. note:: 3/14/2024: I am **Guessing** that the deprecation of numpy.distutils has made Anaconda installs **only** viable in a `virtual environment `_ . I'm also **Guessing** that, on Windows, an Anaconda virtual environment would be successful with the batch file shown above in :ref:`link_windows_bat_file` An older install of Anaconda may work with the **old** and **possibly outdated** approach below. As stated above, the "trick" for installing RocketCEA on Windows seems to be pre-installing the dependency packages (e.g. numpy, scipy and matplotlib) so that the pip options for rocketcea only apply to rocketcea. On Anaconda, many of the required dependencies are preinstalled. To test the required installs, open an Anaconda prompt, launch python and attempt to import each package. (An example is shown below for Anaconda with python 3.9) .. image:: ./_static/Anaconda_check_installs.jpg Notice that a fresh install of Anaconda does not include the `pillow `_ package. use the command:: conda install -c anaconda pillow to install `pillow `_ . The results will look something like the image below. .. image:: ./_static/Anaconda_install_pillow.jpg With all the dependencies handled, the batch file can be much more simple than the one shown above. Before you can run it, you need to verify the location of the python folders under Anaconda. To find your python folder, open an Anaconda prompt, launch python, import sys and give the command "sys.executable" as in the image below. .. image:: ./_static/Anaconda_find_python_exe.jpg In my case, the path was:: C:\Users\Charlie\anaconda3 Yours will likely be similar. For the final step, edit the batch file below to replace **** with the user name shown in the python path above. .. code-block:: batch rem NOTICE: MUST Verify dependency installs prior to running this batch file. SET "MYPYTHONPATH=C:\Users\\anaconda3" rem Make sure that PATH is as simple as possible... For Anaconda notice "\Libary\bin" set PATH=C:\MinGW\mingw64\bin;C:\MinGW\mingw64\lib;%MYPYTHONPATH%;%MYPYTHONPATH%\Scripts;%MYPYTHONPATH%\Library\bin pip install --global-option build_ext --global-option --compiler=mingw32 rocketcea rem Test the compiled module python -c "from rocketcea.cea_obj import CEA_Obj; C=CEA_Obj(oxName='LOX', fuelName='LH2'); print(C.get_Isp())" Run the batch file and the results will hopefully be similar to the results shown below. .. image:: ./_static/Anaconda_successful_install.jpg Notice that the file ran the "quick test" at the bottom of the batch file and properly output the Isp of 374.30... Getting Help ------------ The documentation for RocketCEA is the best place to start. Go to `RocketCEA ReadTheDocs `_ for information. Running RocketCEA ----------------- Any use of RocketCEA begins with an import statement and an instance of CEA_obj:: from rocketcea.cea_obj import CEA_Obj C = CEA_Obj( oxName='LOX', fuelName='LH2') In the above example, LOX and LH2 are called out, but any propellants on the :ref:`Propellants ` page can be used. There are a large number of examples included in this document For instance, look at :ref:`LOX/LH2 Performance ` on the :ref:`Standard Examples ` page. To run an example, highlight the source code with your mouse, right click the highlighted code and select **Copy**. Paste that code into your text editor and save it to a python file.(for example D:\\rocketcea\\example_1.py). Example files can be run with the command:: python example1.py Or, in many text editors hitting the **F5** key will execute the code. Test The Install ---------------- Paste the following code into your text editor and save it to your test folder as basic_cea.py (for example, D:\\rocketcea\\basic_cea.py):: from rocketcea.cea_obj import CEA_Obj C = CEA_Obj( oxName='LOX', fuelName='LH2') for mr in range(2,9): print(mr, C.get_Isp(Pc=100.0, MR=mr, eps=40.0) ) At the command prompt, give the command:: python basic_cea.py If you see the following output:: (2, 424.3597085736007) (3, 445.44434236555196) (4, 453.13271951921837) (5, 453.240429182719) (6, 448.190232998362) (7, 438.74340042907266) (8, 424.6998266323161) Great... you are good to go. If not, see the information below. Google Colaboratory ------------------- If you are having trouble installing RocketCEA on your system, RocketCEA can be run on `Google Colaboratory `_ `Colaboratory `_ is a free Jupyter notebook environment that requires no setup and runs entirely in the cloud. After creating a Colaboratory notebook, install RocketCEA.:: !pip install RocketCEA .. image:: ./_static/colab_pip_rocketcea.jpg :width: 60% If Needed, install libgfortran3:: !apt-get install libgfortran3 .. image:: ./_static/colab_apt_libgfortran3.jpg :width: 70% Create a python script to run RocketCEA:: %%file chk_cea.py from rocketcea.cea_obj import CEA_Obj C = CEA_Obj( oxName='LOX', fuelName='LH2') for mr in range(2,9): print(mr, C.get_Isp(Pc=100.0, MR=mr, eps=40.0) ) .. image:: ./_static/colab_save_pyfile.jpg :width: 60% And then run the file:: !python chk_cea.py .. image:: ./_static/colab_run_chk_cea.jpg :width: 50% Colab plots work with RocketCEA as well. .. image:: ./_static/colab_cstar_plot_example.jpg :width: 80% .. _link_windows_wsl: Windows 10 or 11 with WSL ------------------------- RocketCEA can also be installed on `Windows Subsystem for Linux (WSL) `_ After setting up your Linux distribution on WSL, installing RocketCEA is quick and easy. For example on a fresh Ubuntu distribution, the following will install python 3.10.12 and rocketcea 1.1.34. (Tested March 14, 2024) * Update Ubuntu * sudo apt update && upgrade * configure Ubuntu for python3 and FORTRAN * sudo apt install python3 python3-pip ipython3 * sudo apt-get install gfortran * Install RocketCEA (required libraries should be available) * pip install rocketcea==1.1.34 * Test installation with quick example * python3 -c "from rocketcea.cea_obj import CEA_Obj; C=CEA_Obj(oxName='LOX', fuelName='LH2'); print(C.get_Isp())" * SHOULD RETURN: 374.30361765576896 (or perhaps just very close to it.) WSL GUI ~~~~~~~ Note that, if desired, `VsXsrv `_ can be used to enable Linux-driven graphic windows on WSL. This will enable matplotlib show() command, tkinter programs or any gui-based Linux application installed on the WSL Linux distribution. WSLg ~~~~ In the presumably near future, `WSLg `_ will be available that has GUI support built in. Windows 11 is expected to come with `WSLg `_ and Windows 10 will be able to install `WSLg `_.