{"id":16638275,"url":"https://github.com/combustiontoolbox/combustion_toolbox_sample","last_synced_at":"2025-03-12T02:36:17.019Z","repository":{"id":164397946,"uuid":"639842920","full_name":"CombustionToolbox/combustion_toolbox_sample","owner":"CombustionToolbox","description":"Combustion Toolbox sample","archived":false,"fork":false,"pushed_at":"2024-09-03T08:48:25.000Z","size":4114,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-18T12:15:11.231Z","etag":null,"topics":["app","combustion-toolbox","matlab","matlab-gui","tutorial"],"latest_commit_sha":null,"homepage":"https://combustion-toolbox-website.readthedocs.io","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CombustionToolbox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-12T10:56:18.000Z","updated_at":"2024-09-03T08:47:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"5f434fb2-f08c-462c-ae15-adeba773f8d3","html_url":"https://github.com/CombustionToolbox/combustion_toolbox_sample","commit_stats":null,"previous_names":["combustiontoolbox/combustion_toolbox_sample","albertocuadra/combustion_toolbox_sample"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CombustionToolbox%2Fcombustion_toolbox_sample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CombustionToolbox%2Fcombustion_toolbox_sample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CombustionToolbox%2Fcombustion_toolbox_sample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CombustionToolbox%2Fcombustion_toolbox_sample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CombustionToolbox","download_url":"https://codeload.github.com/CombustionToolbox/combustion_toolbox_sample/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243146058,"owners_count":20243632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app","combustion-toolbox","matlab","matlab-gui","tutorial"],"created_at":"2024-10-12T06:44:09.274Z","updated_at":"2025-03-12T02:36:16.981Z","avatar_url":"https://github.com/CombustionToolbox.png","language":null,"readme":"# Combustion Toolbox: An open-source thermochemical code for gas- and condensed-phase problems involving chemical equilibrium\r\n\r\n**Authors**\r\nAlberto Cuadra, César Huete, Marcos Vera\r\n\r\n**Affiliations**\r\nDepartamento de Ingeniería Térmica y de Fluidos, Universidad Carlos III de Madrid, Spain\r\n\r\n**Corresponding author**\r\nacuadra@ing.uc3m.es (A. Cuadra)\r\n\r\n**Website for online documentation**\r\nhttps://combustion-toolbox-website.readthedocs.io/en/latest/\r\n\r\n**Repository for source code**\r\nhttps://github.com/CombustionToolbox/combustion_toolbox\r\n\r\n---\r\n**Note: This README file is written in [Markdown](https://guides.github.com/features/mastering-markdown/). Please use a Markdown editor to visualize it properly. Otherwise, you can use the [online version](https://github.com/CombustionToolbox/combustion_toolbox_sample) of this file.**\r\n\r\n---\r\n\r\n## 0. Requirements\r\nMATLAB R2021a or higher is required to run the code using the GUI. Otherwise, use the standalone (royalte-free) version of the GUI.\r\n\r\n## 1. Source code\r\n\r\nThe source code of the Combustion Toolbox (CT) contains the following folders and files in the main directory:\r\n\r\n```terminal\r\n.combustion_toolbox\r\n|-- +combustiontoolbox\r\n|-- databases\r\n|-- examples\r\n|-- gui\r\n|-- installer\r\n|-- utils\r\n|-- validations\r\n|-- run_test.m\r\n|-- CODE_OF_CONDUCT.md\r\n|-- CONTENTS.m\r\n|-- CONTRIBUTING.md\r\n|-- CONTRIBUTORS.md\r\n|-- INSTALL.m\r\n|-- LICENSE.md\r\n`-- README.md\r\n```\r\n\r\nThe `+combustiontoolbox` folder encapsulates the different modules (namespaces) implemented in CT, such as CT-EQUIL (*+equilibrium*), CT-SD (*+shockdetonation*), and CT-ROCKET (*+rocket*). The `databases` folder mainly consists of raw data and *.mat* files that contain the thermochemical properties of the individual chemical species. The `examples` folder includes various examples that demonstrate the wide variety of problems that can be solved with CT. The `gui` folder contains the routines that are specifically designed for the GUI. The `installer` folder contains all the installation files of the GUI: the MATLAB toolbox and the royalty-free stand-alone version for different operative systems. The `utils` folder houses utility functions with different purposes. Finally, the `validation` folder includes the routines used to validate CT with the results obtained with other codes, the unit testing files to ensure the correct functionality of the code, and all the graphs generated from these verifications.\r\n\r\nRegarding the files in the main source folder, we have the following: the file `run_test.m` runs the unit tests of CT. The file `CONTENTS.m` is a script that briefly describes the problems that can be solved with CT. The file `INSTALL.m` is a script that installs the CT code and the GUI. The file `LICENSE.md` contains the license of CT (GNU General Public License v3.0). Finally, the file `README.md` is the official description in the GitHub repository.\r\n\r\n\r\nAdditionally, we have included a `sample` folder that contains two subfolders, `input` and `output`. The `input` folder contains the input files for the examples described below in Sec. 3. The `output` folder contains the expected figures to be obtained.\r\n\r\nFor an accurate description of each routine included in the code, please refer to the [online documentation](https://combustion-toolbox-website.readthedocs.io/en/latest/documentation/functions/index.html). For a detailed description of the output, please refer to the manuscript.\r\n\r\nLastly, if there is any question, unexpected behavior, or bug in the code, please use the add-on uifeedback (**we do not collect any data from the sender, it can be totally anonymous**, e.g., as email write @test.com). It can be started by writing in the prompt:\r\n```matlab\r\nuifeedback()\r\n```\r\n\r\n\r\n\r\n## 2. Installation\r\n\r\nCombustion Toolbox can be installed with the provided `INSTALL.m` file. Here is how to install the toolbox:\r\n\r\n1. Navigate to the directory where the code is located.\r\n2. Run the `INSTALL.m` file using the following command in the MATLAB Command Window:\r\n\r\n```matlab\r\nINSTALL()\r\n```\r\n\r\n3. This will add the necessary folders to the MATLAB path and also install the Combustion Toolbox GUI. \r\n\r\n\r\nFor a more detailed description of the installation process, please refer to the [online documentation](https://combustion-toolbox-website.readthedocs.io/en/latest/install.html).\r\n\r\n## 3. Examples\r\n\r\nAs described in the manuscript, CT includes a wide variety of examples and validations in the `examples` and `validations` folders, respectively. In this section, we will describe how to run a simple using MATLAB's desktop environment and the GUI. Additionally, we will show how to run two of the validations carried out in the manuscript. \r\n\r\n### 3.1 Example 1:\r\n\r\nFor this first case, we are going to perform a parametric study of the adiabatic isobaric combustion of acetylene and air at standard conditions ($T = 300$ K, $p = 1$ atm) for a wide range of equivalence ratios $\\phi \\in [0.5, 4]$. This case corresponds with Fig. 4 in the manuscript.\r\n\r\n#### Using the Desktop Environment\r\n\r\nLet's write the following code in the prompt (or run `example_1.m` in the `sample/input` folder):\r\n```matlab\r\n% Import packages\r\nimport combustiontoolbox.databases.NasaDatabase\r\nimport combustiontoolbox.core.*\r\nimport combustiontoolbox.equilibrium.*\r\n% Get Nasa database\r\nDB = NasaDatabase();\r\n% Define chemical system\r\nsystem = ChemicalSystem(DB, 'soot formation extended');\r\n% Initialize mixture\r\nmix = Mixture(system);\r\n% Define chemical state\r\nset(mix, {'C2H2_acetylene'}, 'fuel', 1);\r\nset(mix, {'N2', 'O2'}, 'oxidizer', [79, 21] / 21);\r\n% Define properties\r\nmixArray = setProperties(mix, 'T', 300, 'p', 1, 'equivalenceRatio', 0.5:0.01:4);\r\n% Initialize solver\r\nsolver = EquilibriumSolver('problemType', 'HP');\r\n% Solve problem\r\nsolver.solveArray(mixArray);\r\n% Set displaySpecies\r\ndisplaySpecies = {'CO2', 'CO', 'H2O', 'H2', 'O2', 'N2',...\r\n                  'HCN','H','OH','O','CN','NH3','CH4','C2H4','CH3',...\r\n                  'NO','HCO','NH2','NH','N','CH','Cbgrb'};\r\nsolver.plotConfig.displaySpecies = displaySpecies;\r\n% Generate report\r\nreport(solver, mixArray);\r\n```\r\n\r\nThis will show a summary of the thermodynamic properties and composition of the mixture in the MATLAB Command Window, and the following figures (the expected output is located in './sample/output/example_1' folder):\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_1/example_1_molar_composition.svg\" width=\"1000\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 1.** Variation of the molar fractions $X_j$ for an HP transformation in lean-to-rich acetylene (C$_2$H$_2$)-air mixture at standard conditions ($T_1 = 300$ K, $p = 1$ bar).\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_1/example_1_properties.svg\" width=\"1000\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 2.** Variation of different thermodynamic properties (from left to right): temperature, $T$, pressure, $p$, density, $\\rho$, enthalpy, $h$, internal energy, $e$, Gibbs energy, $g$, entropy, $s$, and adiabatic index, $\\gamma_s$, for an HP transformation in lean-to-rich acetylene (C$_2$H$_2$)-air mixture at standard conditions ($T_1 = 300$ K, $p = 1$ bar).\r\n\r\n\r\n**Note:** This parametric study should take at most 4-6 seconds.\r\n\r\n#### Using the GUI\r\n\r\nThe previous example can also be easly performed using the GUI. To do so, we need to run the GUI using the following command in the MATLAB \r\n```matlab\r\ncombustion_toolbox()\r\n```\r\nor running it directly from MATLAB's Apps tab.\r\n\r\n\r\nOnce the GUI is started, we should see something similar to the following window:\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/input/example_1_gui/gui_cuadra2024_labels_1.svg\" width=\"600\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 3.** Example of how to configure the GUI to reproduce the results of Example 1.\r\n\r\nAs we can observe, the previous figure already includes the necessary inputs to perform the parametric study. The steps to complete the parametric analysis are the following:\r\n\r\n1. Go to the `Quick settings` sub-tab and check the item called `Ideal Air`. With this option, we consider that air is composed of 79% of N$_2$ and 21% of O$_2$ on molar basis.\r\n2. Return to the `inputs` sub-tab and select `Acetylene + Air` as the reactant.\r\n3. Select the list of possible species as products. In this case, we will select a predefined list of species called `Soot formation Extended`, which includes 94 species that typically appear in CHON reactions.\r\n4. Define the parameter to be varied. In this case, we will vary the equivalence ratio $\\phi$ from 0.5 to 4 with a step of 0.05 (decreased to 0.01 for smoother plots). To specify a uniform grid distribution, write `XX:YY:ZZ`, where `XX` represents the start point, `YY` the step size, and `ZZ` the final point. Thus, for this case we have to write `0.5:0.01:4`.\r\n5. Define the problem to be solved. In this case, we will solve the problem for an HP transformation called `HP: Adiabatic T and composition at constant P`.\r\n6. Run the calculation by clicking the `Calculate` button. The default initial state of the mixture corresponds with the standard conditions ($T_1 = 300$ K, $p = 1$ bar).\r\n\r\nOnce the calculation is finished, the lamp located at the bottom of the window should turn green. The results can be visualized in the `results` tab. \r\n\r\nBy clicking the sub-tab `Parameters` and selecting the first case from the tree object, we should see the following:\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_1_gui/gui_cuadra2024_labels_2.svg\" width=\"600\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 4.** Post-processing the results of `Example 1` through the GUI (part I). In particular, the thermodynamic properties correspond to the case selected in the tree object ($\\phi = 0.5$).\r\n\r\nBy clicking the sub-tab `Molar composition` we can observe the molar composition of the mixture (reactants and products):\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_1_gui/gui_cuadra2024_labels_3.svg\" width=\"600\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 5.** Post-processing the results of `Example 1` through the GUI (part II): In particular, the chemical composition corresponds to the case selected in the tree object ($\\phi = 0.5$).\r\n\r\nLastly, the GUI also allows us to visualize the results more interactively. To do so, we need to click the `Custom Figures` sub-tab. Then by selecting the mixture to be plotted as the products (mix2), the equivalence ratio as the parameter to be varied in the x-axis (equivalenceRatio), and the temperature as the property to be plotted in the y-axis (T), we should obtain the following figure:\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_1_gui/gui_cuadra2024_labels_4.svg\" width=\"600\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 6.** Post-processing the results of `Example 1` through the GUI (part III).\r\n\r\n### 3.2 Example 2: \r\n\r\nThis problem consists of a parametric study of a Si-C$_6$H$_5$OH mixture at atmospheric pressure ($p = 1$ atm) for a wide range of temperatures $T \\in [200, 5000]$, which corresponds with Fig. 5 in the manuscript. The results obtained with CT are contrasted with values obtained with the Chemical Equilibrium with Applications (CEA) code.\r\n\r\nWriting in the prompt:\r\n```matlab\r\nrun_validation_TP_CEA_6()\r\n```\r\nwill show two predefined figures (the expected output is located in './sample/output/example_2' folder):\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_2/example_2_molar_composition.svg\" width=\"1000\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 7.** Variation of the molar fractions $X_j$ for a Silica-Phenolic mixture at atmospheric pressure ($p = 1$ atm) with $T \\in [200, 5000]$; solid line: numerical results obtained with CT; symbols: numerical results obtained with NASA's CEA.\r\n\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_2/example_2_properties.svg\" width=\"1000\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 8.** Variation of different thermodynamic mixture properties (from left to right): density, $\\rho$, enthalpy, $h$, internal energy, $e$, Gibbs energy, $g$, specific heat capacity at constant pressure, $c_p$, specific heat capacity at constant pressure, $c_v$, adiabatic index, $\\gamma_s$, derivative of the volume with pressure at constant temperature, $(\\mathrm{d}v/\\mathrm{d}p)_T$, and derivative of the volume with the temperature at constant pressure, $(\\mathrm{d}v/\\mathrm{d}T)_p$, for a Silica-Phenolic mixture at atmospheric pressure ($p = 1$ atm) with $T \\in [200, 5000]$; solid line: numerical results obtained with CT; symbols: numerical results obtained with NASA's CEA.\r\n\r\n**Note:** This parametric study should take 5-7 seconds at most.\r\n\r\n### 3.3 Example 3:\r\n\r\nFor this case, we will obtain the pressure ratio-deflection angle and the incidence angle-deflection angle shock polar diagrams for dry air (consisting of 78% N$_2$, 21% O$_2$, and 1% Ar) initially at room conditions ($T_1 = 300$ K, $p_1 = 1$ atm) at different pre-shock Mach numbers $\\mathcal{M}_1$ = (2, 3, 5, 14). The results obtained with CT are compared with Caltech's SD-Toolbox, which uses Cantera as the kernel for the thermochemical calculations.\r\n\r\nRun the following script:\r\n```matlab\r\nrun_validation_SHOCK_POLAR_SDToolbox_2\r\n```\r\nwhich will show the following figures (the expected output is located in './sample/output/example_3' folder):\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_3/example_3_pressure.svg\" width=\"600\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 9.** Pressure-deflection shock polar diagrams for air (78% N$_2$, 21% O$_2$, and 1% Ar) at pre-shock temperature $T_1 = 300$ K and pressure $p_1 = 1$ atm, and a range of pre-shock Mach numbers $\\mathcal{M}_1$ = (2, 3, 5, 14); solid line: calorically imperfect gas with ionization/dissociation; circles: results obtained with Cantera within Caltech's SD-Toolbox; diamonds: maximum deflection angle $\\theta_{\\rm max}$.\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_3/example_3_wave.svg\" width=\"600\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 10.** Wave angle-deflection ressure-deflection shock polar diagrams for air (78% N$_2$, 21% O$_2$, and 1% Ar) at pre-shock temperature $T_1 = 300$ K and pressure $p_1 = 1$ atm, and a range of pre-shock Mach numbers $\\mathcal{M}_1$ = (2, 3, 5, 14); solid line: calorically imperfect gas with ionization/dissociation; circles: results obtained with Cantera within Caltech's SD-Toolbox; diamonds: maximum deflection angle $\\theta_{\\rm max}$.\r\n\r\n\u003cp align=\"left\"\u003e\r\n    \u003cimg src=\"./sample/output/example_3/example_3_velocity.svg\" width=\"600\"\u003e\r\n\u003c/p\u003e\r\n\r\n**Figure 11.** Post-shock velocity $u_2$ polar diagrams for air (78% N$_2$, 21% O$_2$, and 1% Ar) at pre-shock temperature $T_1 = 300$ K and pressure $p_1 = 1$ atm, and a range of pre-shock Mach numbers $\\mathcal{M}_1$ = (2, 3, 5, 14).\r\n\r\n**Note:** This parametric study should take 5-7 seconds at most.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcombustiontoolbox%2Fcombustion_toolbox_sample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcombustiontoolbox%2Fcombustion_toolbox_sample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcombustiontoolbox%2Fcombustion_toolbox_sample/lists"}