File	Date	Author	Commit
examples	2014-09-26	Michele De Stefano	[760d19] Preparing for the new 2.1.0 release
include	2016-10-04	Michele De Stefano	[2ede32] Doxygen: Upgraded documentation main page
python	2017-01-18	Michele De Stefano	[ff1414] python: Now leaving the C++ standard specificat...
AUTHORS	2014-03-30	Michele De Stefano	[51832f] Cosmetic changes to the documentation
ChangeLog	2014-11-21	Michele De Stefano	[f52c01] Upgraded the ChangeLog and the Doxygen document...
Doxyfile	2014-09-26	Michele De Stefano	[760d19] Preparing for the new 2.1.0 release
INSTALL	2012-10-10	Michele De Stefano	[73b40d] First creation of the repository (at version 1....
LICENSE	2012-10-10	Michele De Stefano	[73b40d] First creation of the repository (at version 1....
Makefile.am	2014-08-14	Michele De Stefano	[737a63] Fixed the distribution scripts.
README	2014-09-28	Michele De Stefano	[06c135] Corrected the README file.
configure.ac	2014-10-05	Michele De Stefano	[13227d] Fixed setup.py detection of NumPy include dir.

Read Me

MDS-UTILS: General purpose utilities for C++ and Python developers
------------------------------------------------------------------

Introduction
------------

This library contains a collection of several C++ utilities for pure C++
development as well as for building Python extensions.

Starting from the 2.0.0 release, a C++ 2011 conforming compiler is nee-
ded. Any build with the previous C++ standard is not supported anymore.
An mds_utils Python package is also provided; it exposes some Boost
uBLAS matrices and vectors to Python. It can be built and installed
using the standard setuptools. It requires SWIG to be present on your
system (the package has been developed and tested with SWIG 2.0.11).
Actually, SWIG is the recommended tool to use when using the mds-utils
library for building Python extensions. The objects exported by the
mds_utils package can be easily reused by other extension modules.
An example is shown in file ublas_pkg_usage.i. The documentation of the
Python package is in docstrings. Once imported, type

   help(mds_utils)

That will be your starting point into the documentation.

Features summary
----------------

MDS-UTILS provides:

    - a tool for detecting machine endianity.
    - utilities for the Boost uBLAS library. Amongst them, some type
      traits for detecting different uBLAS matrix types.
    - some useful classes that allow to treat the old C FILE pointer as
      a C++ stream.
    - C++ wrappers of the main Python objects, independent of those in
      Boost Python. Wrappers are provided also for NumPy arrays.
    - C++ classes that help on treating Python file objects as C++
      streams.
    - a review and refactor of the indexing support in Python exten-
      sions. Now access in write mode is supported too.
    - new C++ to-Python and from-Python converters for some Boost uBlas
      objects and for standard Python objects. These converters do not
      depend on Boost Python.
    - a new sequence iterator that is able to wrap Python sequences and
      allows also to modify them. This feature does not depend on
      Boost.Python.
    - the NDArrayIterator class, that wraps the Numpy C-API iterator and
      allows easy management of conversions to/from Numpy arrays.
    - some SWIG interface files, for easy integration with SWIG exten-
      sions for Python.

Each class is a well-documented, small, easy to use and it should never
be too difficult to learn to use it.
A large percentage of this library makes a heavy usage of the Boost C++
libraries: so, they must be installed on the system. It is assumed that
the user is familiar with them.


Release Notes
-------------

See the ChangeLog file


Installation Instructions
-------------------------

Basically, there is nothing to build, because this library is completely
template based. All that you need is to place the mds_utils folder
(within the include folder) where you prefer.
For Unix/Linux users, installation is facilitated by the GNU build sys-
tem. So, basically, the usual sequence configure, make, make install
will properly install the library. Have a look at the INSTALL file.

If you have downloaded the development version from the repository and
you use a Linux OS you first have to issue "autoreconf -i" into the main
folder. This will create the proper configure and Makefile.in files.
Then you will be able to follow the previous steps.

If you want to build the mds_utils Python package you have to enter the
python directory and issue the command

   python setup.py build

The previous command uses SWIG, so it needs to be installed on the sys-
tem. The package has been developed and tested with SWIG 2.0.11 and I
don't know how it behaves with other SWIG versions. The mds_utils Python
package uses also NumPy and SciPy, so these packages must be present on
the system together with their development headers. For installing the
package issue

   python setup.py install

For detailed instructions on the build process, from within the python
directory, issue the command

   python setup.py --help

and you will be able to see build and installation instructions. It is
recommended to perform the installation of this Python package in two
steps, as explained above. First run the setup.py script with the build
option. Then run it again with the install option. This two-stage in-
stallation is required for working around a bug in Python distutils.


Building the documentation
--------------------------

To build documentation you need doxygen (so, install it if you don't
have). Go into the sources root directory and type

   doxygen

this will create the "doc" directory, containing the whole documenta-
tion.


License
-------

mds_utils is distributed under the MIT license (see the LICENSE file).