1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
|
******
Advice
******
This list is similar to the Advice sections for each chapter in `The C++ Programming Language, Fourth Edition by Bjarne Stroustrup <http://www.stroustrup.com/4th.html>`_
The goal is to provide specific advice and good practices about the use of ADIOS2 in other projects.
1. Use ``MPI_COMM_SELF`` to run MPI compiled versions of ADIOS 2 in "serial" mode
2. Use a runtime configuration file in the ``ADIOS`` constructor or ``adios2_init`` when targeting multiple engines
3. Check object validity when developing (similar to ``fstream``):
- C++: `operator bool`
.. code-block:: c++
if(var) engine.Put(var, data);
- C: NULL pointer
.. code-block:: c
if(var) adios2_put(engine, var, data, adios2_mode_deferred);
- Python: v2 ``__nonzero__`` v3 ``__bool__``. Note: do not check for None object
.. code-block:: python
if(var) engine.Put(var, data);
- Fortran: ``type%valid``
.. code-block:: fortran
if( adios%valid .eqv. .true. ) then
adios2_declare_io(adios, io, "foo")
end if
4. C++11 and Python: use ``try-catch`` (``try-except`` in Python) blocks to handle exceptions from ADIOS 2
5. C++11: use fixed-width types (``int8_t``, ``uint32_t``) for portability
6. Define your data structure: set of variables and attributes before developing. Data hierarchies/models can be built on top of ADIOS 2.
7. Read the documentation for :ref:`Supported Engines` before targeting development for a particular engine
8. MPI development: treat ``ADIOS`` constructor/destructor (``adios2_init``/``adios2_finalize``) and Engine ``Open`` and ``Close`` always as collective functions. For the most part, ADIOS 2 API functionality is local, but other Engine functions might follow other rules, :ref:`Supported Engines`.
9. Use `Remove` functions carefully. They create dangling objects/pointers.
10. Thread-safety: treat ADIOS 2 as NOT thread-safe. Either use a mutex or only handle I/O from a master thread. ADIOS 2 is about performance, adding I/O serial algorithm operations into a parallel execution block may reduce parallel portions from Amdahl's Law.
11. Prefer the high-level Python and C++ APIs for simple tasks that do not require performance. The more familiar Write/Read overloads for File I/O return native data constructs (``std::vector`` and ``numpy arrays``) immediately for a requested selection. ``open`` only explores the metadata index.
12. C++: prefer templates to ``void*`` to increase compile-time safety. Use ``IO::InquireVariableType("variableName")`` and ``adios2::GetType<T>()`` to cast upfront to a ``Variable<T>``. C++17 has ``std::any`` as an alternative to ``void*``. ADIOS 2 follows closely the STL model.
13. Understand ``Put`` and ``Get`` memory contracts from :ref:`Engine`
14. Prefer Put/Get ``Deferred`` mode, treat ``Sync`` as a special mode
15. ``Put Span``: create all spans in a step before populating them. Spans follow the same iterator invalidation rules as ``std::vector``, so use ``span.data()`` to always keep the span pointer up-to-date
16. Always populate data before calling ``Put`` in deferred mode,
and do not change it between ``Put`` and ``EndStep``, or ``Close``
17. Never call ``PerformPuts`` right before ``EndStep``. This was a
code pattern that had no adverse effects with the BP3/4 file
engines and is present in some older code, but was never
beneficial.
18. Use ``BeginStep`` and ``EndStep`` to write code that is portable
across all ADIOS 2 Engine types: file and streaming.
19. Always use ``Close`` for every call to ``Open``.
20. C, Fortran: always call ``adios2_finalize`` for every call to ``adios2_init`` to avoid memory leaks.
21. Reminder: C++, C, Python: Row-Major, while Fortran: Column-Major. ADIOS 2 will handle interoperability between ordering. Remember that :ref:`bpls : Inspecting Data` is always a Row-Major reader so Fortran reader need to swap dimensions seen in bpls. bpls: (slow, ...., fast) -> Fortran(fast,...,slow).
22. Fortran API: use the type members (``var%valid``, ``var%name``, etc.) to get extra type information.
23. Fortran C interoperability: Fortran bindings support the majority of applications using Fortran 90. We currently don't support the ``ISO_C_BINDING`` interoperability module in Fortran 2003.
24. Always keep the ``IO`` object self-contained keeping its own set of ``Variables``, ``Attributes`` and ``Engines``. Do not combine Variables with multiple Engines or multiple modes, unless it's 100% guaranteed to be safe in your program avoiding Variable access conflicts.
25. Developers: explore the testing infrastructure ``ADIOS2/testing`` in ADIOS 2 as a starting point for using ADIOS 2 in your own testing environment.
26. Become a super-user of :ref:`bpls : Inspecting Data` to analyze datasets generated by ADIOS 2.
|
