diff --git a/joss.06963/10.21105.joss.06963.crossref.xml b/joss.06963/10.21105.joss.06963.crossref.xml new file mode 100644 index 0000000000..665bcf3bae --- /dev/null +++ b/joss.06963/10.21105.joss.06963.crossref.xml @@ -0,0 +1,231 @@ + + + + 20241030151253-f2a06a390fe9800579bda985adb4c40be88793ea + 20241030151253 + + JOSS Admin + admin@theoj.org + + The Open Journal + + + + + Journal of Open Source Software + JOSS + 2475-9066 + + 10.21105/joss + https://joss.theoj.org + + + + + 10 + 2024 + + + 9 + + 102 + + + + OpenCCM: An Open-Source Continuous Compartmental +Modelling Package + + + + Alexandru Andrei + Vasile + + Department of Chemical Engineering, University of Waterloo, Ontario, Canada + + https://orcid.org/0000-0002-0233-0172 + + + Matthew Peres + Tino + + Department of Chemical Engineering, University of Waterloo, Ontario, Canada + + https://orcid.org/0009-0005-6832-1761 + + + Yuvraj + Aseri + + Department of Chemical Engineering, University of Waterloo, Ontario, Canada + + https://orcid.org/0009-0008-4703-3711 + + + Nasser Mohieddin + Abukhdeir + + Department of Chemical Engineering, University of Waterloo, Ontario, Canada + Department of Physics and Astronomy, University of Waterloo, Ontario, Canada + Waterloo Institute for Nanotechnology, University of Waterloo, Ontario, Canada + + https://orcid.org/0000-0002-1772-0376 + + + + 10 + 30 + 2024 + + + 6963 + + + 10.21105/joss.06963 + + + http://creativecommons.org/licenses/by/4.0/ + http://creativecommons.org/licenses/by/4.0/ + http://creativecommons.org/licenses/by/4.0/ + + + + Software archive + 10.5281/zenodo.13988255 + + + GitHub review issue + https://github.com/openjournals/joss-reviews/issues/6963 + + + + 10.21105/joss.06963 + https://joss.theoj.org/papers/10.21105/joss.06963 + + + https://joss.theoj.org/papers/10.21105/joss.06963.pdf + + + + + + Cantera: An object-oriented software toolkit +for chemical kinetics, thermodynamics, and transport +processes + Goodwin + 10.5281/zenodo.8137090 + 2023 + Goodwin, D. G., Moffat, H. K., +Schoegl, I., Speth, R. L., & Weber, B. W. (2023). Cantera: An +object-oriented software toolkit for chemical kinetics, thermodynamics, +and transport processes. https://www.cantera.org. +https://doi.org/10.5281/zenodo.8137090 + + + Compartment modelling +software + Quintessa + Quintessa. (n.d.). Compartment +modelling software. Quintessa; Online. Retrieved January 3, 2024, from +https://www.quintessa.org/software/AMBER + + + OpenFOAM v12 user guide + Greenshields + 2024 + Greenshields, C. (2024). OpenFOAM v12 +user guide. The OpenFOAM Foundation. +https://doc.cfd.direct/openfoam/user-guide-v12 + + + OpenCMP: An Open-Source Computational +Multiphysics Package + Monte + Journal of Open Source +Software + 73 + 7 + 10.21105/joss.03742 + 2475-9066 + 2022 + Monte, E. J., Vasile, A. A., Lowman, +J., & Abukhdeir, N. M. (2022). OpenCMP: An Open-Source Computational +Multiphysics Package. Journal of Open Source Software, 7(73), 3742. +https://doi.org/10.21105/joss.03742 + + + A flow alignment-informed method for +compartmental modelling + Vasile + Computers & Chemical +Engineering + 185 + 10.1016/j.compchemeng.2024.108650 + 0098-1354 + 2024 + Vasile, A. A., Aucoin, M. G., Budman, +H., & Abukhdeir, N. M. (2024). A flow alignment-informed method for +compartmental modelling. Computers & Chemical Engineering, 185, +108650. +https://doi.org/10.1016/j.compchemeng.2024.108650 + + + Compartmental modelling in chemical +engineering: A critical review + Jourdan + Chemical Engineering Science + 210 + 10.1016/j.ces.2019.115196 + 0009-2509 + 2019 + Jourdan, N., Neveux, T., Potier, O., +Kanniche, M., Wicks, J., Nopens, I., Rehman, U., & Le Moullec, Y. +(2019). Compartmental modelling in chemical engineering: A critical +review. Chemical Engineering Science, 210, 115196. +https://doi.org/10.1016/j.ces.2019.115196 + + + Model reduction methods + Chinesta + Encyclopedia of computational mechanics +second edition + 10.1002/9781119176817.ecm2110 + 9781119176817 + 2017 + Chinesta, F., Huerta, A., Rozza, G., +& Willcox, K. (2017). Model reduction methods. In Encyclopedia of +computational mechanics second edition (pp. 1–36). John Wiley & +Sons, Ltd. +https://doi.org/10.1002/9781119176817.ecm2110 + + + Model Order Reduction: Volume 3 +Applications + 10.1515/9783110499001 + 2020 + Benner, P., Schilders, W., +Grivet-Talocia, S., Quarteroni, A., Rozza, G., & Miguel Silveira, L. +(Eds.). (2020). Model Order Reduction: Volume 3 Applications. De +Gruyter. https://doi.org/10.1515/9783110499001 + + + The paraview guide: A parallel visualization +application + Ayachit + 2015 + Ayachit, U. (2015). The paraview +guide: A parallel visualization application. Kitware, +Inc. + + + + + + diff --git a/joss.06963/10.21105.joss.06963.pdf b/joss.06963/10.21105.joss.06963.pdf new file mode 100644 index 0000000000..048098b977 Binary files /dev/null and b/joss.06963/10.21105.joss.06963.pdf differ diff --git a/joss.06963/paper.jats/10.21105.joss.06963.jats b/joss.06963/paper.jats/10.21105.joss.06963.jats new file mode 100644 index 0000000000..28bca44eaa --- /dev/null +++ b/joss.06963/paper.jats/10.21105.joss.06963.jats @@ -0,0 +1,711 @@ + + +
+ + + + +Journal of Open Source Software +JOSS + +2475-9066 + +Open Journals + + + +6963 +10.21105/joss.06963 + +OpenCCM: An Open-Source Continuous +Compartmental Modelling Package + + + +https://orcid.org/0000-0002-0233-0172 + +Vasile +Alexandru Andrei + + + + +https://orcid.org/0009-0005-6832-1761 + +Tino +Matthew Peres + + + + +https://orcid.org/0009-0008-4703-3711 + +Aseri +Yuvraj + + + + +https://orcid.org/0000-0002-1772-0376 + +Abukhdeir +Nasser Mohieddin + + + + +* + + + +Department of Chemical Engineering, University of Waterloo, +Ontario, Canada + + + + +Department of Physics and Astronomy, University of +Waterloo, Ontario, Canada + + + + +Waterloo Institute for Nanotechnology, University of +Waterloo, Ontario, Canada + + + + +* E-mail: + +9 +102 +6963 + +Authors of papers retain copyright and release the +work under a Creative Commons Attribution 4.0 International License (CC +BY 4.0) +2022 +The article authors + +Authors of papers retain copyright and release the work under +a Creative Commons Attribution 4.0 International License (CC BY +4.0) + + + +Python +compartmental modelling +reduced order modelling +model order reduction +computational fluid dynamics + + + + + + Summary +

OpenCCM is a compartmental modelling + (Jourdan + et al., 2019) software package based on recently developed + fully automated flow alignment compartmentalization methods + (Vasile + et al., 2024). It is primarily intended for large-scale + flow-based processes with weak coupling between composition changes, + e.g., through (bio)chemical reactions, and convective mass transport + in the system. Compartmental modelling is an important approach used + to develop reduced-order models + (Benner + et al., 2020; + Chinesta + et al., 2017) using a priori knowledge of process hydrodynamics + (Jourdan + et al., 2019). Compartmental modelling methods, such as those + implemented in OpenCCM, enable simulations of + these processes with far less computational complexity while still + capturing the key aspects of process dynamics.

+

OpenCCM integrates with two multiphysics + simulation software packages, OpenCMP + (Monte + et al., 2022) and OpenFOAM + (Greenshields, + 2024), allowing for ease of transferring simulation data for + compartmentalization. Additionally, it provides users with built-in + functionality for computing residence times and exporting for use in + other simulation or visualization software, including + ParaView + (Ayachit, + 2015). Post-processing methods are included for mapping + simulation results from compartment domains to the original simulation + domain, which are useful for visualization purposes and for further + simulations in using other software (e.g., multi-scale modelling).

+
+ + Statement of Need +

Simulation-based design and analysis continue to be widely applied + in the research and development of physicochemical processes. + Processes with large differences in characteristic time and length + scales result in the infeasibility of direct multiphysics simulations + due to computational limitations. This imposes significant + computational costs, which severely reduce the utility of these + simulations for entire classes of processes. Compartmental modeling is + well-suited for such applications because it enables the generatation + of reduced-order models which are less computationally demanding, + frequently by orders of magnitude, compared to direct continuum + mechanical simulations. This is enabled by taking advantage, when + present, of weak couplings between the short and long-time-scale + dynamic phenomena.

+

However, several barriers prevent the more widespread use of + compartmental models. The largest of these is the lack of software for + automating the generation compartmental models. Closed-source software + packages, specifically AMBER + (Quintessa, + n.d.), exists for manually creating and solving well-mixed + compartment networks. However, the cost of these packages are + prohibitive for much of the research community and it lacks automated + compartmentalization. Open-source software, + Cantera + (Goodwin + et al., 2023), also exists to solve compartment networks. + However, it does not incorporate flow information, when available, + either from direct observation or continuum mechanical simulations. + Furthermore, neither of these software allow for the usage and direct + transfer of flow information from continuum mechanical simulations, + such as computational fluid dynamics (CFD) simulations, which are + typically feasible over short (hydrodynamic) time scales.

+

The overall aim of OpenCCM is to fill the + need for an open-source compartmental modeling package that is + user-friendly, compatible with a variety of simulation package + back-ends (e.g., OpenFOAM and + OpenCMP), and which fits into the user’s + existing simulation and post-processing software toolchain, i.e., + ParaView.

+
+ + Features + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FEATUREDESCRIPTION
Model supportAccepts OpenCMP + (Monte + et al., 2022) and OpenFOAM + (Greenshields, + 2024) results
————————-————————————————————————————-
CompartmentalizationSingle-phase flow-based compartment identification
————————-————————————————————————————-
Compartmental ModellingPlug Flow Reactors (PFRs)-in-series-based model
Previous state-of-the-art Continous Stirred-tank reactor + (CSTR)-based models
————————-————————————————————————————-
CM SimulationsLinear, non-linear, and reversible arbitrary + reactions
1st Order upwinding finite-difference-based
Adaptive time-stepping
————————-————————————————————————————-
Post-ProcessingResidence time distribution
————————-————————————————————————————-
OutputIntermediary mesh format
Labeled compartments in Paraview + format
Concentrations from CM simulations in both + Paraview and simulation package + format
————————-————————————————————————————-
PerformanceMulti-threading
Caching of intermediary results to speed up subsequent + runs
+
+
+ + User Interface +

The OpenCCM Python package can be used via + text-based configuration files centred around the command line + interface (CLI), where each simulation run/project is self-contained + in a project directory. In addition to the + OpenCCM configuration files, the required + contents include flow information from one of two open-source + simulation packages: OpenCMP or + OpenFOAM. For OpenCMP + three files are required:

+ + + +

The OpenCMP config file,

+
+ + +

The mesh on which the simulation was run, and

+
+ + +

The .sol solution file containing the velocity profile to + create the compartmental model.

+
+
+

For OpenFOAM, two sub-directories are + required:

+ + + +

The constant/ directory, which contains + the mesh information in ASCII format,

+
+ + +

A directory containing the simulation results, which will be + used to create the compartmental model saved in ASCII format.

+
+
+

The path to the solution directory is specified in the + OpenCCM configuration file and the + constant/ directory is assumed to be in the + same parent folder. OpenCCM will create several + output directories: log/, which contains + detailed debugging information (if enabled); + cache/, which contains intermediary files; and + output_ccm/, which contains both simulation + results of the compartmental model (in various user-specified formats) + and ParaView files for visualization.

+

A sample config file, CONFIG, which outlines + the available parameters, is included in the main directory. An + excerpt of it, showing the compartmental modeling parameters, is shown + below. Square brackets indicate parameters with default values along + with those values indicated inside the brackets.

+ [COMPARTMENT MODELLING] +# Whether to use PFRs-in-series or a CSTR to model each compartment. +model = PFR +# Volumetric flow through a single facet +# below which the flow is considered 0. +flow_threshold_facet = [1e-15] +# Volumetric flow threshold through a surface +# below which the flow is considered 0. +flow_threshold = [1e-15] +# Maximum allowable difference (in % of compartment volume) +# between connections to merge them into one location. +dist_threshold = [5 / 100] +# Absolute tolerances for checking that mass is conserved +# after the flow optimization is performed. +atol_opt = [1e-2] +
+ + Reaction Configuration File +

The chemical reaction parser in OpenCCM + reads and parses the reaction configuration files and can handle + general reaction equations of the form,

+

aA + bB + [...] -> cC + dD + [...]

+

with associated numeric rate constants. It intentionally does not + support the standard <-> symbol for + reversible chemical reactions, so that each independent reaction has + an explicitly defined rate constant. Therefore, a reversible reaction + must be written as two independent forward reactions, each with its + own rate constant. Each species label can contain + letters and numbers, but cannot contain brackets or special + characters, e.g., “(”, “)”, “+”, “-”, “^”. Kinetic rate constants must + be expressed as positive real numbers in standard or scientific + notation. Additionally, each reaction/rate pair must have a unique + identifier (i.e., R1, R2). For example, the + reversible reaction,

+

+ + 2NaCl+CaCO3Na2CO3+CaCl2

+

with + + kf=5e2 + and + + kr=2 + (chosen to be dimensionless for example). A configuration file for + this reversible reaction may then be:

+ [REACTIONS] +R1: 2NaCl + CaCO3 -> Na2CO3 + CaCl2 +R2: Na2CO3 + CaCl2 -> 2NaCl + CaCO3 + +[RATES] +R1: 5e-2 +R2: 2 +

where R1 and R2 are the reaction + identifiers for the forward and reverse reactions, + respectively.

+

An example reaction config file, + CONFIG_REACTIONS, is provided in the main + package directory.

+
+ + Examples of Usage +

Several examples are provided in the OpenCCM + documentation, which demonstrates the using of both + OpenCMP and OpenFOAM + simulation-based flow information for compartmentalization. One + example, located in + examples/OpenCMP/pipe_with_recird_2d/, uses the + geometry from + (Vasile + et al., 2024) and shows how to execute the needed CFD + simulation for flow information (both using + OpenCMP and OpenFOAM), + create/visualize the compartmental model results, and compare the + predicted RTD to the reference result directly from CFD + simulation.

+

For this illustrative example, the steady-state hydrodynamic + flow-profile is obtained by running the OpenCMP + simulation through the run_OpenCMP.py script in + the folder. The resulting flow profile was opened in + ParaView and a line integral convolution + visualization of the velocity field is shown below, coloured by + velocity magnitude.

+ +

Visualization of hydrodynamics from CFD simulation with + line integral convolutions indicating local flow direction and color + corresponding to velocity magnitude.

+ +
+

The underlying velocity field data is then processed using + OpenCCM to generate a network of compartments + by executing the run_compartment.py script. The + figure below shows each element of the original mesh coloured + according to the compartment to which it belongs.

+ +

Visualization of flow-informed compartmentalization with + coloring corresponding to compartment number.

+ +
+

That network of compartments is further processed, as each + compartment is represented by a series of plug-flow reactors (PFRs). + The resulting network (graph) of PFRs is shown in the figure below. + Nodes are the centres of the PFRs and edges are connections (flows) + between PFRs.

+ +

Undirectly graph of the compartment network resulting + from both (i) flow-information compartmentalization and (ii) the use + of spatially-varying compartment approximations + (PFRs).

+ +
+ + RTD Curves +

The residence time distribution (RTD) curve from both the CFD and + compartmental model (CM) simulations is computed using the script in + the supplementary material of + (Vasile + et al., 2024).

+ +

Residence time distribution curves for CFD and CM + simulations.

+ +
+
+ + Reactions +

Finally, to demonstrate how to simulate chemical reaction, an + example is included using the reversible reaction system from + above:

+

+ + 2NaCl+CaCO3Na2CO3+CaCl2

+

with + + kf=5e2 + and + + kr=2 + as the forward and backward rate constants (chosen to be + dimensionless for example). All species have an initial + dimensionless concentration of + + 0 + and have inlet boundary dimensionless concentration values of + + + [NaCl]=[CaCO3]=1 + and + + [Na2CO3]=[CaCl2]=0. + The equations and conditions have already been specified, and the + simulation can be run by using the + run_compartment_w_rxn.py script. Note that + when this script is run multiple times, computational times + following the first will be much shorter in that the compartmental + model is pre-computed (stored within the project directory).

+

To analyze the results, the equilibrium values for this + reversible system are calculated as follows:

+

+ + kf[NaCl]2[CaCO3]=kr[Na2CO3][CaCl2] + + + kfkr=[Na2CO3][CaCl2][NaCl]2[CaCO3] + + + 5×1022=(x)(x)(12x)2(1x) + + + x0.1147

+

where x is the change in + + + CaCO3, + in dimensionless units.

+

The expected equilibrium concentrations for the four species are: + + + [NaCl]=0.7706, + + + [CaCO3]=0.8853, + + + [Na2CO3]=0.1147, + and + + [CaCl2]=0.1147. + Based on the figures below and from direct inspection of the CM + simulation results, correct steady-state values are obtained at the + reactor outlet.

+

+ Input/Output Concentrations for NaCl. + + + Input/Output Concentrations for CaCO3. + + + Input/Output Concentrations for Na2CO3. + + + Input/Output Concentrations for CaCl2. +

+

To output the ParaView visualizations, + change output_VTK to + True in the CONFIG + file and re-run the simulation.

+
+
+ + Acknowledgements +

This research was supported by the Natural Sciences and Engineering + Research Council of Canada (NSERC) and the Digital Research Alliance + of Canada.

+
+ + + + + + + + GoodwinDavid G. + MoffatHarry K. + SchoeglIngmar + SpethRaymond L. + WeberBryan W. + + Cantera: An object-oriented software toolkit for chemical kinetics, thermodynamics, and transport processes + https://www.cantera.org + 2023 + 10.5281/zenodo.8137090 + + + + + + Quintessa + + Compartment modelling software + Quintessa; Online + 20240103 + https://www.quintessa.org/software/AMBER + + + + + + GreenshieldsChristopher + + OpenFOAM v12 user guide + The OpenFOAM Foundation + London, UK + 2024 + https://doc.cfd.direct/openfoam/user-guide-v12 + + + + + + MonteElizabeth Julia + VasileAlexandru Andrei + LowmanJames + AbukhdeirNasser Mohieddin + + OpenCMP: An Open-Source Computational Multiphysics Package + Journal of Open Source Software + 202205 + 20230523 + 7 + 73 + 2475-9066 + 10.21105/joss.03742 + 3742 + + + + + + + VasileAlexandru Andrei + AucoinMarc G. + BudmanHector + AbukhdeirNasser Mohieddin + + A flow alignment-informed method for compartmental modelling + Computers & Chemical Engineering + 2024 + 185 + 0098-1354 + https://www.sciencedirect.com/science/article/pii/S0098135424000681 + 10.1016/j.compchemeng.2024.108650 + 108650 + + + + + + + JourdanNicolas + NeveuxThibaut + PotierOlivier + KannicheMohamed + WicksJim + NopensIngmar + RehmanUsman + Le MoullecYann + + Compartmental modelling in chemical engineering: A critical review + Chemical Engineering Science + 2019 + 210 + 0009-2509 + https://www.sciencedirect.com/science/article/pii/S0009250919306888 + 10.1016/j.ces.2019.115196 + 115196 + + + + + + + ChinestaFrancisco + HuertaAntonio + RozzaGianluigi + WillcoxKaren + + Model reduction methods + Encyclopedia of computational mechanics second edition + John Wiley & Sons, Ltd + 2017 + 9781119176817 + https://onlinelibrary.wiley.com/doi/abs/10.1002/9781119176817.ecm2110 + 10.1002/9781119176817.ecm2110 + 1 + 36 + + + + + Model Order Reduction: Volume 3 Applications + + BennerPeter + SchildersWil + Grivet-TalociaStefano + QuarteroniAlfio + RozzaGianluigi + Miguel SilveiraLuís + + De Gruyter + 2020 + 20230814 + 10.1515/9783110499001 + + + + + + AyachitUtkarsh + + The paraview guide: A parallel visualization application + Kitware, Inc. + 2015 + + + + +
diff --git a/joss.06963/paper.jats/cfd_vs_pfr_vs_cstr.pdf b/joss.06963/paper.jats/cfd_vs_pfr_vs_cstr.pdf new file mode 100644 index 0000000000..c29803450c Binary files /dev/null and b/joss.06963/paper.jats/cfd_vs_pfr_vs_cstr.pdf differ diff --git a/joss.06963/paper.jats/compartment_network.pdf b/joss.06963/paper.jats/compartment_network.pdf new file mode 100644 index 0000000000..fa92dafb4f Binary files /dev/null and b/joss.06963/paper.jats/compartment_network.pdf differ diff --git a/joss.06963/paper.jats/labelled_compartments.png b/joss.06963/paper.jats/labelled_compartments.png new file mode 100644 index 0000000000..61ab93f65d Binary files /dev/null and b/joss.06963/paper.jats/labelled_compartments.png differ diff --git a/joss.06963/paper.jats/lic_domain.png b/joss.06963/paper.jats/lic_domain.png new file mode 100644 index 0000000000..fea6181f84 Binary files /dev/null and b/joss.06963/paper.jats/lic_domain.png differ diff --git a/joss.06963/paper.jats/system_response_CaCO3.pdf b/joss.06963/paper.jats/system_response_CaCO3.pdf new file mode 100644 index 0000000000..b8aeb70800 Binary files /dev/null and b/joss.06963/paper.jats/system_response_CaCO3.pdf differ diff --git a/joss.06963/paper.jats/system_response_CaCl2.pdf b/joss.06963/paper.jats/system_response_CaCl2.pdf new file mode 100644 index 0000000000..f09c73367a Binary files /dev/null and b/joss.06963/paper.jats/system_response_CaCl2.pdf differ diff --git a/joss.06963/paper.jats/system_response_Na2CO3.pdf b/joss.06963/paper.jats/system_response_Na2CO3.pdf new file mode 100644 index 0000000000..ef30500366 Binary files /dev/null and b/joss.06963/paper.jats/system_response_Na2CO3.pdf differ diff --git a/joss.06963/paper.jats/system_response_NaCl.pdf b/joss.06963/paper.jats/system_response_NaCl.pdf new file mode 100644 index 0000000000..d70f56b69e Binary files /dev/null and b/joss.06963/paper.jats/system_response_NaCl.pdf differ