Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Sina as Axom component #1378

Open
wants to merge 56 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
56 commits
Select commit Hold shift + click to select a range
89413c6
establish directory structure and copy/paste headers/sources
bgunnar5 Apr 24, 2024
c8bdb57
add doxygen mainpage for sina
bgunnar5 Apr 24, 2024
4455cc7
first pass at the cmake file for sina component
bgunnar5 Apr 24, 2024
857a449
Merge branch 'LLNL:develop' into feature/bgunnar5/sina-integration
bgunnar5 Apr 29, 2024
d8d7a49
move sina to axom and add cmake files so it can be built
bgunnar5 May 8, 2024
39e5a2e
add doxygen mainpage for sina
bgunnar5 May 8, 2024
a370f6f
merge prior changes to this branch made on diff computer
bgunnar5 May 8, 2024
3c40f1a
Merge branch 'develop' of https://github.com/bgunnar5/axom into featu…
bgunnar5 May 8, 2024
a5fba8b
remove extra adiak list append and uncomment test addition
bgunnar5 May 29, 2024
44e6f74
add tests for sina
bgunnar5 May 29, 2024
f212627
initial add of examples
bgunnar5 May 30, 2024
45628bf
get doxygen docs up and running
bgunnar5 Jun 21, 2024
234e1eb
start work on sphinx docs
bgunnar5 Jun 21, 2024
c9b9cca
finish creating sina docs
bgunnar5 Jun 27, 2024
76c7c86
fix references to sina namespace in doxygen
bgunnar5 Jun 27, 2024
7d78852
add sina fortran interface
bgunnar5 Jul 3, 2024
2fbb425
Merge branch 'develop' of https://github.com/LLNL/axom into feature/b…
bgunnar5 Jul 3, 2024
b23292f
fix small issues with docs
bgunnar5 Jul 9, 2024
d9de3ef
make ordering alphabetical for cmakedefines
bgunnar5 Jul 9, 2024
7bf7fc8
fix indentation on doxygen page
bgunnar5 Jul 9, 2024
f15a501
protect against GMOCK not available
bgunnar5 Jul 9, 2024
46d0fcd
move document examples to actual examples
bgunnar5 Jul 10, 2024
5c181c7
add copyright header to sina files
bgunnar5 Jul 10, 2024
4a635bf
move cpp/hpp files to same directory for core and tests
bgunnar5 Jul 11, 2024
820ce9f
remove CppBridge for C++<14
bgunnar5 Jul 11, 2024
10dccf7
replace AXOM_SINA_USE_ADIAK with AXOM_USE_ADIAK
bgunnar5 Jul 11, 2024
d998fac
change doxygen syntax to match axom's standard
bgunnar5 Jul 12, 2024
4d7c8c2
remove unused config file and reference to msub job in docs
bgunnar5 Jul 16, 2024
2860e09
fix issue with Maestro link
bgunnar5 Jul 16, 2024
c8e1f39
convert Datum to pass by reference
bgunnar5 Jul 16, 2024
6f271a3
Merge branch 'develop' of https://github.com/LLNL/axom into feature/b…
bgunnar5 Jul 16, 2024
a57111a
run make style
bgunnar5 Jul 17, 2024
66c3163
Merge branch 'develop' into pr-from-fork/1376
bgunnar5 Jul 17, 2024
917aa27
disable sina for osx_gcc and windows azure tests
bgunnar5 Aug 1, 2024
b9b415b
add custom sina matchers so that blueos will build
bgunnar5 Aug 1, 2024
a516da9
Merge branch 'pr-from-fork/1376' of https://github.com/LLNL/axom into…
bgunnar5 Aug 1, 2024
48b311f
Merge branch 'develop' of https://github.com/LLNL/axom into feature/b…
bgunnar5 Aug 1, 2024
3ef59eb
remove code check call from Sina CMake and run make style
bgunnar5 Aug 5, 2024
5856843
add compiler flag for xl fortran builds
bgunnar5 Aug 7, 2024
5d39439
Merge branch 'develop' of https://github.com/LLNL/axom into feature/b…
bgunnar5 Aug 7, 2024
70b4716
Merge branch 'develop' of https://github.com/LLNL/axom into feature/b…
bgunnar5 Aug 7, 2024
f9285ca
Merge branch 'develop' of https://github.com/LLNL/axom into feature/b…
bgunnar5 Aug 8, 2024
64ce0ec
update sina description in doxygen mainpage
bgunnar5 Aug 8, 2024
0ee8cf9
Merge branch 'develop' of https://github.com/LLNL/axom into feature/b…
bgunnar5 Aug 12, 2024
4552083
add version for sina
bgunnar5 Aug 12, 2024
0c279e3
Merge branch 'develop' into pr-from-fork/1376
rhornung67 Aug 15, 2024
caab17d
Update src/axom/sina/core/ID.hpp
bgunnar5 Aug 30, 2024
bce3aaa
implementation -> header in hpp file brief statements
bgunnar5 Aug 30, 2024
274851f
make docs suggestions from PR
bgunnar5 Aug 30, 2024
528d0d9
modify code block comments for docs
bgunnar5 Aug 30, 2024
6246b2d
some final fixes for sina docs
bgunnar5 Aug 30, 2024
dbf9d5a
fix python interpreter package find to not use deprecated call
bgunnar5 Aug 30, 2024
ae026bf
move custom XL flag to just be used for sina fortran example executable
bgunnar5 Aug 30, 2024
cbcbce0
Merge branch 'develop' of https://github.com/LLNL/axom into feature/b…
bgunnar5 Aug 30, 2024
03aca6d
Merge branch 'pr-from-fork/1376' of https://github.com/LLNL/axom into…
bgunnar5 Aug 30, 2024
7289033
fix python executable variable name
bgunnar5 Sep 4, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
start work on sphinx docs
  • Loading branch information
bgunnar5 committed Jun 21, 2024
commit 234e1eb82dfdb550fe6fdb52ad901f3f7dd0e62c
25 changes: 25 additions & 0 deletions src/axom/sina/docs/sphinx/core_concepts.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
.. ##
.. ## SPDX-License-Identifier: (BSD-3-Clause)

=============
Core Concepts
=============

Sina provides four main classes:

- ``Document`` - represents the top-level object of a JSON file conforming to the Sina schema.
- ``Record`` - represents the data to be stored.
- ``Relationship`` - represents a way to define the relationship between two ``Record`` objects.
- ``CurveSet`` - a class to store related independent and dependent ``Curve`` objects.
bgunnar5 marked this conversation as resolved.
Show resolved Hide resolved

More details on each class can be found in their respective pages below.

.. toctree::
:maxdepth: 2

documents
records
relationships
curve_sets
10 changes: 10 additions & 0 deletions src/axom/sina/docs/sphinx/curve_sets.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
.. ##
.. ## SPDX-License-Identifier: (BSD-3-Clause)

.. _curvesets-label:

==========
Curve Sets
==========
10 changes: 10 additions & 0 deletions src/axom/sina/docs/sphinx/documents.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
.. ##
.. ## SPDX-License-Identifier: (BSD-3-Clause)

.. _documents-label:

=========
Documents
=========
44 changes: 44 additions & 0 deletions src/axom/sina/docs/sphinx/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
.. ##
.. ## SPDX-License-Identifier: (BSD-3-Clause)

===================
Sina C++ User Guide
===================

The Sina C++ library can read and write JSON files in the Sina schema. It
can be used by simulation applications to summarize run data to be ingested
into a database using the Sina tool suite.

The top-level object in the Sina schema is the Document. It contains lists
of Record and Relationship objects. The example below shows the basics.
For more details, see the `Tutorial <tutorial.rst>`_.

.. literalinclude:: ../../examples/sina_basic.cpp
:language: cpp

After running the above, the file "MySinaData.json" will contain the
following:

.. code:: json

{
"records": [
{
"application": "My Sim Code",
"local_id": "run1",
"type": "run",
"user": "jdoe",
"version": "1.2.3"
}
],
"relationships": []
}

.. toctree::
:caption: Contents
:maxdepth: 2

tutorial
core_concepts
10 changes: 10 additions & 0 deletions src/axom/sina/docs/sphinx/records.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
.. ##
.. ## SPDX-License-Identifier: (BSD-3-Clause)

.. _records-label:

=======
Records
=======
10 changes: 10 additions & 0 deletions src/axom/sina/docs/sphinx/relationships.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
.. ##
.. ## SPDX-License-Identifier: (BSD-3-Clause)

.. _relationships-label:

=============
Relationships
=============
174 changes: 174 additions & 0 deletions src/axom/sina/docs/sphinx/tutorial.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,174 @@
.. ## Copyright (c) 2017-2024, Lawrence Livermore National Security, LLC and
.. ## other Axom Project Developers. See the top-level LICENSE file for details.
.. ##
.. ## SPDX-License-Identifier: (BSD-3-Clause)

.. _tutorial-label:

========
Tutorial
========

This short tutorial walks you through the basic usage of the Sina library.
For more in-depth details, see the documentation for the individual classes,
such as Record, Relationship, and Document.

.. contents:: Tutorial Contents
:depth: 2

------------------------------
Creating Documents and Records
------------------------------

The basic working units in Sina are the Document, Record, and Relationship.
A Document is a collection of Records and Relationships. A Record contains
information about a particular entity, such as the run of an application,
or a description of a UQ study. A Relationship describes how two records
bgunnar5 marked this conversation as resolved.
Show resolved Hide resolved
relate to each user (e.g. UQ studies contain runs).

This first example shows how to create a record:

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 9-16
bgunnar5 marked this conversation as resolved.
Show resolved Hide resolved

The record has an ID "some_record_id", which is unique to the enclosing
document (it will be replaced by a global ID upon ingestion). The only
required field for records is their type, which is "my_record_type" in this
case. Once created, a record can be added to a Document.

We can create Runs. Runs are special types of records. They have the required
fields of application ("My Sim Code"), version ("1.2.3"), and user ("jdoe").
The type is automatically set to "run".

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 20-27

-----------
Adding Data
-----------

Once we have a Record, we can add different types of data to it. Any Datum
object that is added will end up in the "data" section of the record in
the JSON file.

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 31-45

-----------------
Adding Curve Sets
-----------------

While you can add data items that are vectors of numbers, sometimes you want
to express relationships between them. For example, you may want to express
the fact that a timeplot captures the fact that there is an independent
variable (e.g. "time"), and possibly multiple dependent variables (e.g.
"temperature" and "energy").

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 49-66

------------
Adding Files
------------

It is also useful to add to a record a set of files that it relates to.
For example your application generated some external data, or you want to
point to a license file.

Conversely, at times it may be necessary to remove a file from the record's file list.
For example if the file was deleted or renamed.

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 72-78

-----------------------------
Relationships Between Records
-----------------------------

Relationships between objects can be captured via the Relationship class.
This relates two records via a user-defined predicate. In the example below,
a new relashionship is created between two records: a UQ study and a run. The
study is said to "contain" the run. As a best practice, predicates should
be active verbs, such as "contains" in "the study contains the run", rather
than "is part of", as in "the run is part of the study".

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 83-85

---------------------
Library-Specific Data
---------------------

Oftentimes, simulation codes are composed of multiple libraries. If those
offer a capability to collect data in a Sina document, you can leverage that
to expose this additional data in your records.

For example, suppose you are using libraries named ``foo`` and ``bar``.
library ``foo`` defines ``foo_collectData()`` like this:

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 90-93

Library ``bar`` defines ``bar_gatherData()`` like this:

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 97-100

In your host application, you can define sections for ``foo`` and ``bar``
to add their own data.

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 104-112

In the example above, once the record is ingested into a Sina datastore,
users will be able to search for "temperature" (value = 450),
"foo/temperature" (value = 500), and "bar/temperature" (value = 400).

----------------
Input and Output
----------------

Once you have a document, it is easy to save it to a file. After executing
the below, your will output a file named "my_output.json" which you can ingest
into a Sina datastore.

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 116-118

If needed, you can also load a document from a file. This can be useful,
for example, if you wrote a document when writing a restart and you want to
continue from where you left off.

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 122-124

---------------------------------
Non-Conforming, User-Defined Data
---------------------------------

While the Sina format is capable of expressing and indexing lots of different
types of data, there may be special cases it doesn't cover well. If you want
to add extra data to a record but don't care if it doesn't get indexed, you
can add it to the "user_defined" section of records (or libraries of
a record). This is a JSON object that will be ignored by Sina for
processing purposes, but will be brought back with your record if you
retrieve it from a database.

Sina uses `Conduit <https://llnl-conduit.readthedocs.io/>`_ to
convert to and from JSON. The user-defined section is exposed as a
`Conduit Node <https://llnl-conduit.readthedocs.io/en/latest/tutorial_cpp_basics.html#node-basics>`_.

.. literalinclude:: ../../examples/sina_tutorial.cpp
:language: cpp
:lines: 128-137
5 changes: 5 additions & 0 deletions src/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ are identified.
* Primal: Computational geometry primitives
* Quest: Querying on surface tool
* Sidre: Simulation data repository
* Sina: Write data in a common file format
* Slam: Set-theoretic lightweight API for meshes
* Slic: Simple Logging Interface Code
* Spin: Spatial index structures for managing and accelerating spatial searches
Expand Down Expand Up @@ -98,6 +99,9 @@ User guides and source code documentation are always linked on this site.
* - Sidre
- :doc:`User Guide <axom/sidre/docs/sphinx/index>`
- `Source documentation <doxygen/html/sidretop.html>`__
* - Sina
- :doc:`User Guide <axom/sina/docs/sphinx/index>`
- `Source documentation <doxygen/html/sinatop.html>`__
* - Slam
- :doc:`User Guide <axom/slam/docs/sphinx/index>`
- `Source documentation <doxygen/html/slamtop.html>`__
Expand Down Expand Up @@ -206,6 +210,7 @@ LLNL-CODE-741217
Primal (Computational geometry primitives) <axom/primal/docs/sphinx/index>
Quest (Querying on surface tool) <axom/quest/docs/sphinx/index>
Sidre (Simulation data repository) <axom/sidre/docs/sphinx/index>
Sina (Write data in a common format) <axom/sina/docs/sphinx/index>
Slam (Set-theoretic lightweight API for meshes) <axom/slam/docs/sphinx/index>
Slic (Simple Logging Interface Code) <axom/slic/docs/sphinx/index>
Spin (Spatial indexes) <axom/spin/docs/sphinx/index>
Expand Down