-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
197 lines (151 loc) · 7.79 KB
/
README
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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
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
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
======================
Library libnpy
======================
CONTENTS
1. INTRODUCTION
2. INSTALLATION
2.1. Short instructions
2.2. Explanatory remarks
3. USAGE
4. INSTRINSICS
4.1. Format of .npy files
4.2. Provided functions / subroutines
4.3. Discussion of pro- and contra- of provided INSTALL_FLAVOR options
5. CHANGELOG
=======================
1. INTRODUCTION
This is a small library for writing an array to a .npy file, so that it
can easily be loaded into a numpy application. The library can be called
from a C/C++ application. Moreover, Fortran wrappers are available.
If you are looking for a more sophisticated solution, have a look at
hdf file format (hierarchical data format) or netcdf library or
cnpy library.
2. INSTALLATION
2.1. Short instructions
cp archs/arch.inc.gcc arch.inc
vim arch.inc
make
make check
make install
2.2. Explanatory remarks
There is a Makefile-based build system, which can be customized for
your particular set of C/C++/Fortran/Python compilers by means of
an architechture file "arch.inc". The architecture file must be created
in the librarie's root directory (together with this README file).
Examples of "arch.inc" files are available in the directory "archs/".
One can copy one of these examples and adjust for your particular
machine/compiler set.
During adjustment you should set the C/C++ compiler, optionally fortran
compiler, optionally for testing purposes python2 and python3
interpreters, a PREFIX for installation directories. Moreover, an
INSTALLATION_FLAVOR should be chosen. INSTALLATION_FLAVOR can be chosen
out of three possibilities
i) c_only_bindings -- library will be usable only from C/C++ programs.
ii) fortran_mod -- the fortran wrappers will be added to the library
in form of a fortran module.
iii) fortran_nomod -- the fortran wrappers will be added to the library
without utilizing fortran modules.
For additional discussion of these possibilities we refer to section
4. INTRINSICS (subsection 4.3).
By invoking "make" command one starts the compilation process of all
three flavors of the library. The command "make check" will additionally
create test executables which are capable of creating a set of .npy files.
These .npy files will be then read by python scripts and compared to the
reference data.
The command "make install" copies the "npy.h" header file to the
directory $(PREFIX)/include/, as well as "libnpy.a" library file to the
directory $(PREFIX)/lib/. If INSTALLATION_FLAVOR==fortran_mod,
then a .mod file "fnpy.mod" will be put into $(PREFIX)/include/ directory.
3. USAGE
The usage of the library is best illustrated by examples.
Example of a C program that creates .npy files can be found under
"test/test_npy.c". Example of a fortran program can be found under
"test/test_fnpy_mod.F90". This program USEs the module fnpy which provides
a description of interfaces. Finally, an example of a Fortran program that
would not USE any module file is available under "test/test_fnpy_nomod.F90".
Reading of .npy files occurs only from a python script. Examples of such
scripts are available under src/*.py
4. INTRINSICS
4.1. Format of .npy files
For a description of the NUMPY file format, do
>> from numpy.lib import format
>> help(format)
The od (octal dump) command provides a simple way to look at the contents
of a .npy file, and especially to check the metadata:
>> od -c file.npy
4.2. Provided functions / subroutines
The library provides the C functions
npy_save
npy_save_double
npy_save_float
npy_save_int
npy_save_float_complex
npy_save_double_complex
If you require Fortran bindings with a module interface, then you
should choose INSTALL_FLAVOR=fortran_mod. The Fortran module fnpy
(fnpy.mod) will define the subroutines
save_single
save_double
save_integer
save_complex_single
save_complex_double
If you require Fortran bindings without the module interface, then you
should choose INSTALL_FLAVOR=fortran_nomod. The library "libnpy.a"
will contain subroutines named similarly to the BLAS/LAPACK library:
inpys -- Integer array .NPY Save
snpys -- Single precision real arrays .NPY Save
dnpys -- Double precision real arrays .NPY Save
cnpys -- Single precision complex arrays .NPY Save
znpys -- Double precision complex arrays .NPY Save
In all cases, the C function npy_save can write any type of array; the
others are convenience routines that call npy_save.
4.3. Discussion of pro- and contra- of provided INSTALL_FLAVOR options
We have chosen to provide three installation flavors because of
portability reasons.
Namely, if you choose the INSTALL_FLAVOR=c_only_bindings option, then
your compilation will be not hampered by a (eventually) missing Fortran
compiler. However, if calling from a Fortran source, you would not profit
from the Fortran wrappers provided by other two options
(fortran_mod or fortran_nomod).
The choice INSTALL_FLAVOR=fortran_mod will cause an addition of the
Fortran wrapper subroutines into the library "libnpy.a". Moreover, this
option will additionally install a module file "fnpy.mod" to the
$(PREFIX)/include/ subdirectory. This file is a binary, compiler-specific
file that provides an exhaustive information on the argument's types of
the Fortran wrapper subroutines "save_*". This choice results in an
early detection of argument-passing errors, because these errors would
be detected automatically at the compilation time. However, the .mod
file should be generally produced by the same compiler which will be
used in your application. The latter circumstance often makes unusable
the library if one tries to use different Fortran compilers for the
library and application.
The choice INSTALL_FLAVOR=fortran_nomod will cause addition of yet
other Fortran wrapper subroutines (*npys) into the library "libnpy.a".
However, this option would not install any additional header-like file.
This choice obvoiusly adds to the vulnerability of the application because
the eventual argument-passing errors could not be detected at the
compilation time. However, the _nomod wrappers do not require any .mod
file and do not produce any fortran-specific dependencies in the
"libnpy.a" (at least if compiled with gfortran without extra debug
options). This is a pre-requisite for a portable library, i.e. library
that can be successfully used with different Fortran compilers on the
application side.
5. CHANGELOG
31/05/2009 Version 0.1
12/10/2009 Version 0.2: Change sizeof(...) to (int) sizeof(...) in
third argument of sprintf() to stop warnings from gcc-4.4.1. Changed
int shape[ndims] to int* shape to work around a problem with nvcc,
the Nvidia cuda compiler (requested by Stéphane Gaudreault).
12/10/2009 Version 0.3: Modified include/npy.h to add extern "C" when
compiled with C++ (suggested by Stéphane Gaudreault).
04/06/2010 Version 0.4: Added support for MAC OSX (patch provided
by Vladimir Chalupecky). Modified the makefile so that the Fortran
bindings are optional. The header file npy.h now provides a const
string LIBNPY_VERSION giving the library version.
18/03/2011 Version 0.5: Changed src/check_npy.py so that the for-loop
is not executed when the file is imported as a module. This change was
in response to an email from Mark Rosin, who observed that
'make check_fortran' fails if you do not first run 'make check'.
02/10/2014 Version 0.6: Substantial changes in the library:
three INSTALLATION_FLAVORS, own implementation of htole16, reimplemented
tests, etc. by Peter Koval.