ReadMe.md 8.19 KB
Newer Older
1
2
3
[![GitHub (pre-)release](https://img.shields.io/github/release/ornladios/adios2/all.svg)]()
[![GitHub license](http://dmlc.github.io/img/apache2.svg)](./LICENSE)

Atkins, Charles Vernon's avatar
Atkins, Charles Vernon committed
4

Atkins, Charles Vernon's avatar
Atkins, Charles Vernon committed
5
6
7
8
[![Circle CI](https://circleci.com/gh/ornladios/ADIOS2.svg?style=shield)](https://circleci.com/gh/ornladios/ADIOS2)
[![Travis CI](https://travis-ci.org/ornladios/ADIOS2.svg)](https://travis-ci.org/ornladios/ADIOS2)
[![AppVeyor CI](https://ci.appveyor.com/api/projects/status/0s2a3qp57hgbvlhj?svg=true)](https://ci.appveyor.com/project/ornladios/adios2)

9
10
# Adaptable Input / Output System (ADIOS) v2.1.0
This is v2.1.0 of the ADIOS I/O system, developed as part of the
11
12
13
14
15
16
17
18
19
U.S. Department of Energy Exascale Computing Program.

## License
ADIOS >= 2.0 is licensed under the Apache License v2.0.  See the accompanying
Copyright.txt for more details.

## Directory layout

* cmake - Project specific CMake modules
20
* examples - ADIOS2 Examples
21
* scripts - Project maintenance and development scripts
22
23
24
25
* source - Main ADIOS2 source  
    * adios2 - source directory for the ADIOS2 library to be installed    under install-dir/lib/libadios2.  
    * utils  - source directory for the binary utilities, to be installed under install-dir/bin  
* bindings - Additional language bindings (C, Fortran and Python)
26
27
* testing - Tests

28
29
30
31
32
33
34
## Documentation
Please find ADIOS2 software documentation online under the project GitHub wiki:
[https://github.com/ornladios/ADIOS2/wiki](https://github.com/ornladios/ADIOS2/wiki)

To generate Doxygen application programming interface (API) documentation see 
instructions under: [doc/ReadMe.md](doc/ReadMe.md)  

35
36
## Getting Started

37
38
39
ADIOS2 uses CMake for its build environment.  CMake expects projects
to use "out-of-source" builds, which means keeping a separate build and source
directory (different from autotools, which usually uses an in-source build).
40

41
To build ADIOS2:
William F Godoy's avatar
William F Godoy committed
42

43
1. Clone the repository:
44
45
46
47
48
49
50

```bash
$ mkdir adios2
$ cd adios2
$ git clone https://github.com/ornladios/adios2.git source
```

51
2. Create a separate build directory:
William F Godoy's avatar
William F Godoy committed
52

53
54
55
56
57
58
59
60
```bash
$ mkdir build
```

3. Configure the project with CMake:

```bash
$ cd build
61
$ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios2/2.1.0/gnu/openmpi ../source
62
63
64
65
66
-- The C compiler identification is GNU 6.3.1
-- The CXX compiler identification is GNU 6.3.1
...

ADIOS2 build configuration:
67
  ADIOS Version: 2.1.0
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
  C++ Compiler : GNU 6.3.1
    /usr/bin/c++

  Installation prefix: /opt/adios2/2.0.0/gnu/openmpi
  Features:
    Library Type: shared
    Build Type:   Debug
    Testing: ON
    Build Options:
      BZip2    : ON
      ZFP      : OFF
      MPI      : ON
      DataMan  : ON
      ZeroMQ   : ON
      HDF5     : ON
      ADIOS1   : OFF
      Python   : ON
85
      C        : ON
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
      SysVShMem: ON

-- Configuring done
-- Generating done
-- Build files have been written to: /home/chuck/Code/adios2/build
$
```

The following options can be specified with CMake's `-DVAR=VALUE` syntax to control which features get enabled or disabled:

| CMake Option         | Values              | Description                                                                      |
| :------------------- | :-------------------------: | :------------------------------------------------------------------------------- |
| `ADIOS2_USE_BZip2`   | **`AUTO`**/``ON``/``OFF`` | Enable [BZip2](http://www.bzip.org/) compression (not implemented).              |
| `ADIOS2_USE_ZFP`     | **`AUTO`**/``ON``/``OFF`` | Enable [ZFP](https://github.com/LLNL/zfp) compression (not implemented).         |
| `ADIOS2_USE_MPI`     | **`AUTO`**/``ON``/``OFF`` | Enable MPI.                                                                      |
| `ADIOS2_USE_DataMan` | **`AUTO`**/``ON``/``OFF`` | Enable the DataMan engine for WAN transports.                                    |
| `ADIOS2_USE_ZeroMQ`  | **`AUTO`**/``ON``/``OFF`` | Enable ZeroMQ for the DataMan engine.                                            |
| `ADIOS2_USE_HDF5`    | **`AUTO`**/``ON``/``OFF`` | Enable the [HDF5](https://www.hdfgroup.org) engine.                              |
| `ADIOS2_USE_ADIOS1`  | **`AUTO`**/``ON``/``OFF`` | Enable the [ADIOS 1.x](https://www.olcf.ornl.gov/center-projects/adios/) engine. |
| `ADIOS2_USE_Python`  | **`AUTO`**/``ON``/``OFF`` | Enable the Python >= 2.7 bindings. |

107
Note: The `ADIOS2_USE_HDF5` and `ADIOS2_USE_ADIOS1` options require the use of a matching serial or parallel version depending on whether `ADIOS2_USE_MPI` is enabled.  Similary, enabling MPI and Python bindings requires the presence of `mpi4py`.
108
109
110
111
112
113
114
115
116
117
118

In addition to the `ADIOS2_USE_Feature` options, the following options are also available to control how the library get's built:

| CMake Options              | Values                                                    | Description                                                                           |
| :------------------------- | :-------------------------------------------------------: | :------------------------------------------------------------------------------------ |
| `ADIOS2_BUILD_SHARED_LIBS` | **`ON`**/`OFF`                                            | Build shared libraries.                                                               |
| `ADIOS2_ENABLE_PIC`        | **`ON`**/`OFF`                                            | Enable Position Independent Code for static libraries.                                |
| `ADIOS2_BUILD_EXAMPLES`    | **`ON`**/`OFF`                                            | Build examples.                                                                       |
| `ADIOS2_BUILD_TESTING`     | **`ON`**/`OFF`                                            | Build test code.                                                                      |
| `CMAKE_INSTALL_PREFIX`     | /path/to/install (`/usr/local`)                           | Install location.                                                                     |
| `CMAKE_BUILD_TYPE`         | **`Debug`** / `Release` / `RelWithDebInfo` / `MinSizeRel` | The level of compiler optimization to use.                                            |
William F Godoy's avatar
William F Godoy committed
119
120
121

4. Compile:

122
123
124
```bash
$ make -j8
```
William F Godoy's avatar
William F Godoy committed
125
126
127

5. Run tests:

128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
```bash
$ ctest
Test project /home/chuck/Code/adios2/build
      Start  1: ADIOSInterfaceWriteTest.DefineVarChar1x10
 1/31 Test  #1: ADIOSInterfaceWriteTest.DefineVarChar1x10 ..............   Passed    0.00 sec
      Start  2: ADIOSInterfaceWriteTest.DefineVarShort1x10
 2/31 Test  #2: ADIOSInterfaceWriteTest.DefineVarShort1x10 .............   Passed    0.00 sec
...
      Start 21: HDF5WriteReadTest.ADIOS2HDF5WriteHDF5Read1D8
21/31 Test #21: HDF5WriteReadTest.ADIOS2HDF5WriteHDF5Read1D8 ...........   Passed    0.01 sec
      Start 22: HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read1D8
22/31 Test #22: HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read1D8 .....***Not Run (Disabled)   0.00 sec
      Start 23: HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read1D8
23/31 Test #23: HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read1D8 ...........***Not Run (Disabled)   0.00 sec
...
      Start 30: PythonBPWrite
30/31 Test #30: PythonBPWrite ..........................................   Passed    0.12 sec
      Start 31: XMLConfigTest.TwoIOs
31/31 Test #31: XMLConfigTest.TwoIOs ...................................   Passed    0.01 sec

100% tests passed, 0 tests failed out of 25

Total Test time (real) =   0.29 sec

The following tests did not run:
	 22 - HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read1D8 (Disabled)
	 23 - HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read1D8 (Disabled)
	 25 - HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read2D2x4 (Disabled)
	 26 - HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read2D2x4 (Disabled)
	 28 - HDF5WriteReadTest.ADIOS2HDF5WriteADIOS2HDF5Read2D4x2 (Disabled)
	 29 - HDF5WriteReadTest.HDF5WriteADIOS2HDF5Read2D4x2 (Disabled)
$
```

6.  Install:
```
$ make install
[  7%] Built target adios2sys_objects
...
[ 61%] Built target adios2
[ 68%] Built target adios2py
...
Install the project...
-- Install configuration: "Debug"
172
-- Installing: /opt/adios2/2.1.0/gnu/openmpi/include/adios2/ADIOSConfig.h
173
...
174
-- Installing: /opt/adios2/2.1.0/gnu/openmpi/bin/adios2-config
175
...
176
-- Installing: /opt/adios2/2.1.0/gnu/openmpi/include/adios2.h
177
...
178
179
180
-- Installing: /opt/adios2/2.1.0/gnu/openmpi/lib/libadios2.so.2.0.0
-- Installing: /opt/adios2/2.1.0/gnu/openmpi/lib/libadios2.so.2
-- Installing: /opt/adios2/2.1.0/gnu/openmpi/lib/libadios2.so
181
182
183
...
$
```