1.. ## Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and
2.. ## other Axom Project Developers. See the top-level LICENSE file for details.
3.. ##
4.. ## SPDX-License-Identifier: (BSD-3-Clause)
5
6****
7Axom
8****
9
10Axom is an open source project that provides robust and flexible software
11components that serve as building blocks for high performance scientific
12computing applications. A key goal of the project is to have different
13application teams co-develop and share general core infrastructure software
14across their projects instead of individually developing and maintaining
15capabilities that are similar in functionality but are not easily shared.
16
17An important objective of Axom is to facilitate integration of novel,
18forward-looking computer science capabilities into simulation codes.
19A pillar of Axom design is to enable and simplify the exchange of
20simulation data between applications and tools. Axom developers
21emphasize the following principles in software design and implementation:
22
23  * Start design and implementation based on concrete application use cases and maintain flexibility to meet the needs of a diverse set of applications
24  * Develop high-quality, robust, high performance software that has well-designed APIs, good documentation, and solid testing
25  * Apply consistent software engineering practices across all Axom components so developers can easily work on them
26  * Ensure that components integrate well together and are easy for applications to adopt
27
28The main drivers of Axom capabilities originate in the needs of multiphysics
29applications in the `Advanced Simulation and Computing (ASC) Program <https://asc.llnl.gov>`_ at `Lawrence Livermore National Laboratory (LLNL) <https://www.llnl.gov>`_ . However, Axom can be employed in a wide range of applications
30beyond that scope, including research codes, proxy application, etc. Often,
31developing these types of applications using Axom can facilitate technology
32transfer from research efforts into production applications.
33
34==============
35Axom Software
36==============
37
38Axom software components are maintained and developed on the
39`Axom GitHub Project <https://github.com/LLNL/axom>`_.
40
41.. note:: While Axom is developed in C++, its components have native
42          interfaces in C and Fortran for straightforward usage in
43          applications developed in those languages. Python interfaces
44          are in development.
45
46Our current collection of components is listed here. The number of
47components and their capabilities will expand over time as new needs
48are identified.
49
50   * Inlet: Input file parsing and information storage/retrieval
51   * Klee: Shaping specification and implementation
52   * Lumberjack: Scalable parallel message logging and filtering
53   * Mint: Mesh data model
54   * Primal: Computational geometry primitives
55   * Quest: Querying on surface tool
56   * Sidre: Simulation data repository
57   * Slam: Set-theoretic lightweight API for meshes
58   * Slic: Simple Logging Interface Code
59   * Spin: Spatial index structures for managing and accelerating spatial searches
60
61=============
62Documentation
63=============
64
65User guides and source code documentation are always linked on this site.
66
67  * :doc:`Quickstart Guide <docs/sphinx/quickstart_guide/index>`
68  *  `Source documentation <doxygen/html/index.html>`__
69
70.. list-table::
71   :align: center
72
73   * - Core
74     - :doc:`User Guide <axom/core/docs/sphinx/index>`
75     - `Source documentation <doxygen/html/coretop.html>`__
76   * - Inlet
77     - :doc:`User Guide <axom/inlet/docs/sphinx/index>`
78     - `Source documentation <doxygen/html/inlettop.html>`__
79   * - Klee
80     - :doc:`User Guide <axom/klee/docs/sphinx/index>`
81     - `Source documentation <doxygen/html/kleetop.html>`__
82   * - Lumberjack
83     - :doc:`User Guide <axom/lumberjack/docs/sphinx/index>`
84     - `Source documentation <doxygen/html/lumberjacktop.html>`__
85   * - Mint
86     - :doc:`User Guide <axom/mint/docs/sphinx/index>`
87     - `Source documentation <doxygen/html/minttop.html>`__
88   * - Primal
89     - :doc:`User Guide <axom/primal/docs/sphinx/index>`
90     - `Source documentation <doxygen/html/primaltop.html>`__
91   * - Quest
92     - :doc:`User Guide <axom/quest/docs/sphinx/index>`
93     - `Source documentation <doxygen/html/questtop.html>`__
94   * - Sidre
95     - :doc:`User Guide <axom/sidre/docs/sphinx/index>`
96     - `Source documentation <doxygen/html/sidretop.html>`__
97   * - Slam
98     - :doc:`User Guide <axom/slam/docs/sphinx/index>`
99     - `Source documentation <doxygen/html/slamtop.html>`__
100   * - Slic
101     - :doc:`User Guide <axom/slic/docs/sphinx/index>`
102     - `Source documentation <doxygen/html/slictop.html>`__
103   * - Spin
104     - :doc:`User Guide <axom/spin/docs/sphinx/index>`
105     - `Source documentation <doxygen/html/spintop.html>`__
106
107
108============================
109Component Level Dependencies
110============================
111
112Axom has the following inter-component dependencies:
113
114- Core has no dependencies and the other components depend on Core
115- Slic optionally depends on Lumberjack
116- Slam, Spin, Primal, Mint, Quest, and Sidre depend on Slic
117- Mint optionally depends on Sidre
118- Inlet depends on Sidre, Slic, and Primal
119- Klee depends on Sidre, Slic, Inlet and Primal
120- Quest depends on Slam, Spin, Primal, Mint, and, optionally, Klee
121
122The figure below summarizes these dependencies. Solid links indicate hard
123dependencies; dashed links indicate optional dependencies.
124
125.. graphviz:: docs/dependencies.dot
126
127
128======================================================
129Other Tools Application Developers May Find Useful
130======================================================
131
132The Axom team develops and supports other software tools that are useful
133for software projects independent of the Axom. These include:
134
135  *  `BLT <https://github.com/LLNL/blt>`_ CMake-based build system developed by the Axom team to simplify CMake usage and development tool integration
136  *  `Shroud <https://github.com/LLNL/shroud>`_ Generator for C, Fortran, and Python interfaces to C++ libraries, and Fortran and Python interfaces to C libraries
137  *  `Conduit <https://github.com/LLNL/conduit>`_ Library for describing and managing in-memory simulation data
138
139===================
140Developer Resources
141===================
142
143Folks interested in contributing to Axom may be interested in our developer
144resource guides.
145
146  * :doc:`Developer Guide <docs/sphinx/dev_guide/index>`
147  * :doc:`Coding Guide <docs/sphinx/coding_guide/index>`
148
149================================
150Communicating with the Axom Team
151================================
152
153--------------
154Mailing Lists
155--------------
156
157The most effective way to communicate with the Axom team is by using one
158of our email lists:
159
160  * 'axom-users@llnl.gov' is for Axom users to contact developers to ask questions, report issues, etc.
161  * 'axom-dev@llnl.gov' is mainly for communication among Axom team members
162
163
164---------
165Chat Room
166---------
167
168We also have the 'Axom' chat room on the LLNL Microsoft Teams server. This
169is open to anyone with access to the LLNL network. Just log onto Teams and
170join the room.
171
172
173======================================================
174Axom Copyright and License Information
175======================================================
176
177Please see the :ref:`axom-license`.
178
179Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC.
180Produced at the Lawrence Livermore National Laboratory.
181
182LLNL-CODE-741217
183
184
185.. toctree::
186   :hidden:
187
188   docs/sphinx/quickstart_guide/index
189
190.. toctree::
191   :hidden:
192   :titlesonly:
193   :caption: Component User Guides
194
195   Core (Widely useful utilities) <axom/core/docs/sphinx/index>
196   Inlet (Input files) <axom/inlet/docs/sphinx/index>
197   Klee (Shaping specification and implementation) <axom/klee/docs/sphinx/index>
198   Lumberjack (Scalable parallel message logging and filtering) <axom/lumberjack/docs/sphinx/index>
199   Mint (Mesh data model) <axom/mint/docs/sphinx/index>
200   Primal (Computational geometry primitives) <axom/primal/docs/sphinx/index>
201   Quest (Querying on surface tool) <axom/quest/docs/sphinx/index>
202   Sidre (Simulation data repository) <axom/sidre/docs/sphinx/index>
203   Slam (Set-theoretic lightweight API for meshes) <axom/slam/docs/sphinx/index>
204   Slic (Simple Logging Interface Code) <axom/slic/docs/sphinx/index>
205   Spin (Spatial indexes) <axom/spin/docs/sphinx/index>
206
207.. toctree::
208   :hidden:
209   :caption: Developer Resources
210
211   docs/sphinx/dev_guide/index
212   docs/sphinx/coding_guide/index
213   docs/licenses
214