updated paper with a diagram

paper/diagram.tex

@@ -0,0 +1,34 @@
+\documentclass[12pt]{standalone}
+\usepackage{tikz}
+\usepackage[T1]{fontenc}
+\usepackage{listings}
+\lstset{basicstyle=\ttfamily}
+
+\renewcommand{\familydefault}{\sfdefault}
+\usetikzlibrary{calc,patterns,decorations.pathreplacing,calligraphy}
+\tikzstyle{bag} = [align=center]
+\begin{document}
+\begin{tikzpicture}[scale = 0.8, transform shape, every node/.style={draw,outer sep=0pt,thick}]    
+
+\node[bag] (pde) at (6,0) [minimum width=3cm,minimum height=1cm] {PDE constraint \\ \lstinline{soupy.VariationalPDEControlProblem}};
+\node[bag] (qoi) at (0,0) [minimum width=3cm,minimum height=1cm] {Quantity of interest \\ \lstinline{soupy.ControlQoI}};
+\node[bag] (model) at (6,-2) [minimum width=3cm,minimum height=1cm] {Input-output model \\ \lstinline{soupy.ControlModel}};
+\node[bag] (prior) at (12,-2) [minimum width=3cm,minimum height=1cm] {Sampling distribution \\ \lstinline{hippylib.Prior}};
+\node[bag] (risk) at (6,-4) [minimum width=3cm,minimum height=1cm] {Risk measure \\ \lstinline{RiskMeasure}};
+\node[bag] (penalty) at (0,-4) [minimum width=3cm,minimum height=1cm] {Penalization \\ \lstinline{soupy.Penalization}};
+\node[bag] (cost) at (6,-6) [minimum width=3cm,minimum height=1cm] {Cost functional \\ \lstinline{soupy.ControlCostFunctional}};
+
+\node[bag] (optimize) at (6,-8.5) [minimum width=3cm,minimum height=1cm] {Optimizer\\ \lstinline{soupy.Optimization} or \\ \lstinline{scipy.optimize}};
+
+\draw[-stealth] (pde.south) -- (model.north); 
+\draw[-stealth] (model.south) -- (risk.north); 
+\draw[-stealth] (risk.south) -- (cost.north); 
+\draw[-stealth] (cost.south) -- (optimize.north); 
+
+\draw[-stealth] (qoi.south) -- (0,-2) -- (model.west); 
+\draw[-stealth] (prior.south) -- (12,-4) -- (risk.east); 
+\draw[-stealth] (penalty.south) -- (0,-6) -- (cost.west); 
+
+
+\end{tikzpicture}
+\end{document}

paper/paper.bib

@@ -139,3 +139,16 @@ @Article{ChenGhattas21
   publisher = {SIAM},
   timestamp = {2021-10-14},
 }
+
+@article{MituschFunkeDokken2019, 
+  doi = {10.21105/joss.01292}, 
+  url = {https://doi.org/10.21105/joss.01292}, 
+  year = {2019}, 
+  publisher = {The Open Journal}, 
+  volume = {4}, 
+  number = {38}, 
+  pages = {1292}, 
+  author = {Sebastian K. Mitusch and Simon W. Funke and Jørgen S. Dokken}, 
+  title = {dolfin-adjoint 2018.1: automated adjoints for FEniCS and Firedrake}, 
+  journal = {Journal of Open Source Software} 
+}

paper/paper.md

@@ -67,18 +67,31 @@ Computation of risk measures typically requires sampling or other forms of quadr
 This results in a complex optimization problem in which each evaluation of the optimization objective requires numerous solutions of the underlying PDE.
 
 SOUPy provides a platform to formulate and solve such PDE-constrained OUU problems using efficient derivative-based optimization methods. 
-SOUPy makes use of FEniCS, an open source finite-element library, to create and solve the underlying PDEs. 
+Users supply the definitions for the PDE constraint, QoI, and additional penalization terms for the optimization variable, and are given the option to choose from a suite of used risk measures.
+At its core, SOUPy implements sample-based evaluation of risk measures and their derivatives, where parallel-in-sample computation is supported through MPI. 
+The resulting cost functionals can then be minimized using SOUPy's implementations of large-scale optimization algorithms, such as L-BFGS [@LiuNocedal89] and Inexact Newton-CG [@EisenstatWalker96; @Steihaug83], 
+or through algorithms available in SciPy [@2020SciPy-NMeth] using the provided interface. \autoref{fig:diagram} shows the key components of a PDE-constrained OUU problem and their corresponding classes in the SOUPy.
+
+![Structure of a PDE-constrained OUU problem, illustrating the main components and their corresponding classes as implemented in SOUPy.](diagram.pdf)
+
+
+
+Several open-source software packages such as dolfin-adjoint [@MituschFunkeDokken2019] and hIPPYlib 
+provide the capabilities for solving PDE-constrained optimization problems with generic PDEs through adjoint-based computation of derivatives. 
+However, these packages largely focus on the deterministic setting. 
+Instead, SOUPY integrates these capabilities with risk measures approximations to address problems in PDE-constrained OUU.
+To this end, SOUPy makes use of FEniCS, an open source finite-element library, to create and solve the underlying PDEs. 
+The unified form language used by FEniCS also allows users to conveniently define the PDE, QoI, and penalization terms using their variational forms.
+SOUPy is also integrated with hIPPYlib, an open source library for large-scale inverse problems, 
+adopting its framework for adjoint-based derivative computation and algorithms for efficient sampling of random fields.
+
+<!-- To this end, SOUPy makes use of FEniCS, an open source finite-element library, to create and solve the underlying PDEs. 
 The unified form language used by FEniCS allows users to conveniently define the PDE in its weak form, 
 as well as the form of the QoI and any additional penalization terms on the optimization variable. 
 SOUPy is also integrated with hIPPYlib, an open source library for large-scale inverse problems, 
-adopting its framework for adjoint-based computation of derivatives and efficient sampling of random fields.
-At its core, SOUPy implements sample-based evaluation of risk measures and their derivatives, where parallel-in-sample computation is supported through MPI. 
-The risk measures are used to define cost functions, 
-which can be minimized using custom implementations of large-scale optimization algorithms such as L-BFGS [@LiuNocedal89] and Inexact Newton-CG [@EisenstatWalker96; @Steihaug83], 
-or through algorithms available in SciPy [@2020SciPy-NMeth] using the provided interface. 
-
-Several existing software packages, such as dolfin-adjoint, hIPPYlib, 
+adopting its framework for adjoint-based computation of derivatives and efficient sampling of random fields. -->
 
+SOUPy can be used by researchers to rapidly prototype formulations and solutions PDE-constrained OUU problems.
 Additionally, SOUPy aims to facilitate the development and testing of novel algorithms for PDE-constrained OUU. 
 For example, SOUPy has been used in the development of methods for the optimization of turbulent flows [@ChenVillaGhattas19], metamaterial design [@ChenHabermanGhattas21], and groundwater extraction [@ChenGhattas21].
 It has also been used to obtain baselines for the development of machine learning approaches for PDE-constrained OUU [@LuoOLearyRoseberryChenEtAl23].