======================
   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.