Skip to content

Commit

Permalink
Creating 10.21105.joss.06654.jats
Browse files Browse the repository at this point in the history
  • Loading branch information
@editorialbot
editorialbot committed Jun 24, 2024
1 parent 0382cdb commit 1f4c962
Showing 1 changed file with 336 additions and 0 deletions.
336 changes: 336 additions & 0 deletions joss.06654/paper.jats/10.21105.joss.06654.jats
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,336 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.2 20190208//EN"
"JATS-publishing1.dtd">
<article xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:xlink="http://www.w3.org/1999/xlink" dtd-version="1.2" article-type="other">
<front>
<journal-meta>
<journal-id></journal-id>
<journal-title-group>
<journal-title>Journal of Open Source Software</journal-title>
<abbrev-journal-title>JOSS</abbrev-journal-title>
</journal-title-group>
<issn publication-format="electronic">2475-9066</issn>
<publisher>
<publisher-name>Open Journals</publisher-name>
</publisher>
</journal-meta>
<article-meta>
<article-id pub-id-type="publisher-id">6654</article-id>
<article-id pub-id-type="doi">10.21105/joss.06654</article-id>
<title-group>
<article-title><italic>Hypredrive</italic>: High-level interface for
solving linear systems with <italic>hypre</italic></article-title>
</title-group>
<contrib-group>
<contrib contrib-type="author">
<contrib-id contrib-id-type="orcid">https://orcid.org/0000-0002-3389-523X</contrib-id>
<name>
<surname>Magri</surname>
<given-names>Victor A. P.</given-names>
</name>
<xref ref-type="aff" rid="aff-1"/>
</contrib>
<aff id="aff-1">
<institution-wrap>
<institution>Lawrence Livermore National Laboratory, CA,
USA</institution>
</institution-wrap>
</aff>
</contrib-group>
<pub-date date-type="pub" publication-format="electronic" iso-8601-date="2024-03-30">
<day>30</day>
<month>3</month>
<year>2024</year>
</pub-date>
<volume>9</volume>
<issue>98</issue>
<fpage>6654</fpage>
<permissions>
<copyright-statement>Authors of papers retain copyright and release the
work under a Creative Commons Attribution 4.0 International License (CC
BY 4.0)</copyright-statement>
<copyright-year>2022</copyright-year>
<copyright-holder>The article authors</copyright-holder>
<license license-type="open-access" xlink:href="https://creativecommons.org/licenses/by/4.0/">
<license-p>Authors of papers retain copyright and release the work under
a Creative Commons Attribution 4.0 International License (CC BY
4.0)</license-p>
</license>
</permissions>
<kwd-group kwd-group-type="author">
<kwd>linear solvers</kwd>
<kwd>preconditioning</kwd>
<kwd>algebraic multigrid</kwd>
<kwd>high performance computing</kwd>
</kwd-group>
</article-meta>
</front>
<body>
<sec id="summary">
<title>Summary</title>
<p>Solving sparse linear systems of equations is an essential task for
many application codes in computational science and engineering.
Commonly used mathematical libraries for addressing these problems
include, among others,
<ext-link ext-link-type="uri" xlink:href="https://trilinos.github.io/index.html">trilinos</ext-link>
(<xref alt="Heroux et al., 2005" rid="ref-trilinos" ref-type="bibr">Heroux
et al., 2005</xref>),
<ext-link ext-link-type="uri" xlink:href="https://petsc.org/">PETSc</ext-link>
(<xref alt="Balay et al., 2024" rid="ref-petsc" ref-type="bibr">Balay
et al., 2024</xref>) and
<ext-link ext-link-type="uri" xlink:href="https://github.com/hypre-space/hypre"><italic>hypre</italic></ext-link>
(<xref alt="Falgout &amp; Yang, 2002" rid="ref-hypre" ref-type="bibr">Falgout
&amp; Yang, 2002</xref>). The first two allow for quick testing of
different solution strategies through input files, a feature that
<italic>hypre</italic> currently lacks. <italic>Hypredrive</italic>
aims to fill this gap by providing a simple and user-friendly
interface to <italic>hypre</italic>. Inspired by the solver
composability support in PETSc via
<ext-link ext-link-type="uri" xlink:href="https://petsc.org/main/manual/other/#the-options-database"><monospace>.petscrc</monospace>
files</ext-link> and the flexible configuration framework used in
spack
(<xref alt="Gamblin et al., 2015" rid="ref-spack" ref-type="bibr">Gamblin
et al., 2015</xref>), <italic>hypredrive</italic> allows users to
easily configure and switch solver options in <italic>hypre</italic>
through input files in
<ext-link ext-link-type="uri" xlink:href="https://yaml.org/spec/1.2/spec.html">YAML</ext-link>
format, making experimentation with different solver techniques more
accessible to researchers and software developers who work with
numerical simulation codes.</p>
</sec>
<sec id="statement-of-need">
<title>Statement of need</title>
<p><italic>Hypre</italic> is a widely used and efficient linear solver
package; however, the complexity associated with its direct use might
limit <italic>hypre</italic> users and application developers to
explore with different solver options. <italic>Hypredrive</italic>
bridges this gap by providing a high-level and lightweight interface
to <italic>hypre</italic>, encapsulating its complexity while
retaining its capabilities with minimal computational overhead.</p>
</sec>
<sec id="software-capabilities">
<title>Software capabilities</title>
<p><italic>Hypredrive</italic> is a software package written in C that
includes a library with APIs designed to simplify the interaction with
<italic>hypre</italic> and an executable driver for performing the
solution of linear systems defined via YAML input files. The types of
linear systems solvable with <italic>hypredrive</italic> are
determined by <italic>hypre</italic>. Key features of the software
are:</p>
<list list-type="bullet">
<list-item>
<p><bold>Encapsulation</bold>: <monospace>libHYPREDRV</monospace>
wraps the function calls for building solvers and preconditioners
in <italic>hypre</italic> through an intuitive YAML interface
driven by configuration files. This design ensures a
straightforward way of setting up solvers in
<italic>hypre</italic> and sharing options without recompiling the
user’s application code.</p>
</list-item>
<list-item>
<p><bold>Prototyping</bold>: <monospace>hypredrive</monospace>
allows users to prototype rapidly, comparing the performance of
various solver options and tweaking parameters directly through
the YAML configuration file. This flexibility encourages
experimentation, helping users identify the most effective solver
strategies for their specific problems.</p>
</list-item>
<list-item>
<p><bold>Testing</bold>: <monospace>hypredrive</monospace> enables
the creation of an integrated testing framework to evaluate
solvers against a set of predefined linear systems. This feature
lets users understand whether updates to <italic>hypre</italic>
lead to different solver convergence or performance for their
problems of interest.</p>
</list-item>
</list>
</sec>
<sec id="example-usage">
<title>Example usage</title>
<p>As an example usage of <monospace>hypredrive</monospace>, consider
the solution of a linear system arising from a seven points finite
difference discretization of the Laplace equation on a
<monospace>10x10x10</monospace> cartesian grid. Both sparse matrix and
right hand side vector are stored at
<monospace>data/ps3d10pt7/np1/</monospace>. For solving this linear
system with algebraic multigrid (BoomerAMG) as a preconditioner to the
conjugate gradient iterative solver, the YAML input file
<monospace>input.yml</monospace> would look like:</p>
<code language="yaml">linear_system:
rhs_filename: data/ps3d10pt7/np1/IJ.out.b
matrix_filename: data/ps3d10pt7/np1/IJ.out.A
solver: pcg
preconditioner: amg</code>
<p>while <monospace>hypredrive</monospace> can be executed via</p>
<code language="bash">$ mpirun -np 1 ./hypredrive input.yml</code>
<p>yielding an output that looks like:</p>
<preformat>Date and time: YYYY-MM-DD HH:MM:SS

Using HYPRE_DEVELOP_STRING: HYPRE_VERSION_GOES_HERE

Running on 1 MPI rank
-------------------------------------------------------------------------------
linear_system:
rhs_filename: data/ps3d10pt7/np1/IJ.out.b
matrix_filename: data/ps3d10pt7/np1/IJ.out.A
solver: pcg
preconditioner: amg
-------------------------------------------------------------------------------
===============================================================================
Solving linear system #0 with 1000 rows and 6400 nonzeros...
===============================================================================


STATISTICS SUMMARY:

+----------+-------------+-------------+-------------+-------------+----------+
| | LS build | setup | solve | relative | |
| Entry | times | times | times | res. norm | iters |
+----------+-------------+-------------+-------------+-------------+----------+
| 0 | 0.004 | 0.002 | 0.001 | 4.98e-08 | 6 |
+----------+-------------+-------------+-------------+-------------+----------+

Date and time: YYYY-MM-DD HH:MM:SS
${HYPREDRIVE_PATH}/hypredrive done!</preformat>
<p>This example shows the minimal set of options in
<monospace>hypredrive</monospace>’s input file needed for running the
executable. Specific parameter/value pairs for controlling the setup
of preconditioners and solvers can be added to the input file, leading
to different convergence behaviors. For a complete list of available
parameters and more detailed input file examples, see
<ext-link ext-link-type="uri" xlink:href="https://hypredrive.readthedocs.io/en/latest/"><italic>hypredrive</italic>’s
manual</ext-link>.</p>
</sec>
<sec id="acknowledgements">
<title>Acknowledgements</title>
<p>This work was performed under the auspices of the U.S. Department
of Energy by Lawrence Livermore National Laboratory under Contract
DE-AC52-07NA27344 (LLNL-JRNL-865058).</p>
</sec>
</body>
<back>
<ref-list>
<title></title>
<ref id="ref-hypre">
<element-citation publication-type="paper-conference">
<person-group person-group-type="author">
<name><surname>Falgout</surname><given-names>Robert D.</given-names></name>
<name><surname>Yang</surname><given-names>Ulrike Meier</given-names></name>
</person-group>
<article-title>Hypre: A library of high performance preconditioners</article-title>
<source>Computational science — ICCS 2002</source>
<person-group person-group-type="editor">
<name><surname>Sloot</surname><given-names>Peter M. A.</given-names></name>
<name><surname>Hoekstra</surname><given-names>Alfons G.</given-names></name>
<name><surname>Tan</surname><given-names>C. J. Kenneth</given-names></name>
<name><surname>Dongarra</surname><given-names>Jack J.</given-names></name>
</person-group>
<publisher-name>Springer Berlin Heidelberg</publisher-name>
<publisher-loc>Berlin, Heidelberg</publisher-loc>
<year iso-8601-date="2002">2002</year>
<isbn>978-3-540-47789-1</isbn>
<pub-id pub-id-type="doi">10.1007/3-540-47789-6_66</pub-id>
<fpage>632</fpage>
<lpage>641</lpage>
</element-citation>
</ref>
<ref id="ref-trilinos">
<element-citation publication-type="article-journal">
<person-group person-group-type="author">
<name><surname>Heroux</surname><given-names>Michael A.</given-names></name>
<name><surname>Bartlett</surname><given-names>Roscoe A.</given-names></name>
<name><surname>Howle</surname><given-names>Vicki E.</given-names></name>
<name><surname>Hoekstra</surname><given-names>Robert J.</given-names></name>
<name><surname>Hu</surname><given-names>Jonathan J.</given-names></name>
<name><surname>Kolda</surname><given-names>Tamara G.</given-names></name>
<name><surname>Lehoucq</surname><given-names>Richard B.</given-names></name>
<name><surname>Long</surname><given-names>Kevin R.</given-names></name>
<name><surname>Pawlowski</surname><given-names>Roger P.</given-names></name>
<name><surname>Phipps</surname><given-names>Eric T.</given-names></name>
<name><surname>Salinger</surname><given-names>Andrew G.</given-names></name>
<name><surname>Thornquist</surname><given-names>Heidi K.</given-names></name>
<name><surname>Tuminaro</surname><given-names>Ray S.</given-names></name>
<name><surname>Willenbring</surname><given-names>James M.</given-names></name>
<name><surname>Williams</surname><given-names>Alan</given-names></name>
<name><surname>Stanley</surname><given-names>Kendall S.</given-names></name>
</person-group>
<article-title>An overview of the Trilinos project</article-title>
<source>ACM Trans. Math. Softw.</source>
<publisher-name>Association for Computing Machinery</publisher-name>
<publisher-loc>New York, NY, USA</publisher-loc>
<year iso-8601-date="2005-09">2005</year><month>09</month>
<volume>31</volume>
<issue>3</issue>
<issn>0098-3500</issn>
<uri>https://doi.org/10.1145/1089014.1089021</uri>
<pub-id pub-id-type="doi">10.1145/1089014.1089021</pub-id>
<fpage>397</fpage>
<lpage>423</lpage>
</element-citation>
</ref>
<ref id="ref-petsc">
<element-citation publication-type="report">
<person-group person-group-type="author">
<name><surname>Balay</surname><given-names>Satish</given-names></name>
<name><surname>Abhyankar</surname><given-names>Shrirang</given-names></name>
<name><surname>Adams</surname><given-names>Mark F.</given-names></name>
<name><surname>Benson</surname><given-names>Steven</given-names></name>
<name><surname>Brown</surname><given-names>Jed</given-names></name>
<name><surname>Brune</surname><given-names>Peter</given-names></name>
<name><surname>Buschelman</surname><given-names>Kris</given-names></name>
<name><surname>Constantinescu</surname><given-names>Emil</given-names></name>
<name><surname>Dalcin</surname><given-names>Lisandro</given-names></name>
<name><surname>Dener</surname><given-names>Alp</given-names></name>
<name><surname>Eijkhout</surname><given-names>Victor</given-names></name>
<name><surname>Faibussowitsch</surname><given-names>Jacob</given-names></name>
<name><surname>Gropp</surname><given-names>William D.</given-names></name>
<name><surname>Hapla</surname><given-names>Václav</given-names></name>
<name><surname>Isaac</surname><given-names>Tobin</given-names></name>
<name><surname>Jolivet</surname><given-names>Pierre</given-names></name>
<name><surname>Karpeev</surname><given-names>Dmitry</given-names></name>
<name><surname>Kaushik</surname><given-names>Dinesh</given-names></name>
<name><surname>Knepley</surname><given-names>Matthew G.</given-names></name>
<name><surname>Kong</surname><given-names>Fande</given-names></name>
<name><surname>Kruger</surname><given-names>Scott</given-names></name>
<name><surname>May</surname><given-names>Dave A.</given-names></name>
<name><surname>McInnes</surname><given-names>Lois Curfman</given-names></name>
<name><surname>Mills</surname><given-names>Richard Tran</given-names></name>
<name><surname>Mitchell</surname><given-names>Lawrence</given-names></name>
<name><surname>Munson</surname><given-names>Todd</given-names></name>
<name><surname>Roman</surname><given-names>Jose E.</given-names></name>
<name><surname>Rupp</surname><given-names>Karl</given-names></name>
<name><surname>Sanan</surname><given-names>Patrick</given-names></name>
<name><surname>Sarich</surname><given-names>Jason</given-names></name>
<name><surname>Smith</surname><given-names>Barry F.</given-names></name>
<name><surname>Zampini</surname><given-names>Stefano</given-names></name>
<name><surname>Zhang</surname><given-names>Hong</given-names></name>
<name><surname>Zhang</surname><given-names>Hong</given-names></name>
<name><surname>Zhang</surname><given-names>Junchao</given-names></name>
</person-group>
<article-title>PETSc/TAO users manual</article-title>
<publisher-name>Argonne National Laboratory</publisher-name>
<year iso-8601-date="2024">2024</year>
<pub-id pub-id-type="doi">10.2172/2205494</pub-id>
</element-citation>
</ref>
<ref id="ref-spack">
<element-citation publication-type="paper-conference">
<person-group person-group-type="author">
<name><surname>Gamblin</surname><given-names>Todd</given-names></name>
<name><surname>LeGendre</surname><given-names>Matthew</given-names></name>
<name><surname>Collette</surname><given-names>Michael R.</given-names></name>
<name><surname>Lee</surname><given-names>Gregory L.</given-names></name>
<name><surname>Moody</surname><given-names>Adam</given-names></name>
<name><surname>Supinski</surname><given-names>Bronis R. de</given-names></name>
<name><surname>Futral</surname><given-names>Scott</given-names></name>
</person-group>
<article-title>The Spack package manager: Bringing order to HPC software chaos</article-title>
<publisher-loc>Austin, Texas, USA</publisher-loc>
<year iso-8601-date="2015">2015</year>
<uri>https://github.com/spack/spack</uri>
<pub-id pub-id-type="doi">10.1145/2807591.2807623</pub-id>
</element-citation>
</ref>
</ref-list>
</back>
</article>

0 comments on commit 1f4c962

Please sign in to comment.