merge dev into master (#16)

* add missing files * fix unittest * fix unittest * unittest on appveyor * cleanup appveyor; cleanup docs * shuffle location of c++ docs * update c++ docs * small tweak * update docs * include oalib.py in package documentation * documentation updates * upgrade doxyfile; update paper * documentation fixes * fix for rtd * add logo file * fix rtd * fix rtd * fix rtd * fix rtd * build package on rtd * build package on rtd * fix rtd build * move oadoxy.i * update to python 3.6 on rtd * on rtd only swig * rtd import oalib.py * fix rtd * fix rtd * fix rtd * rtd conda build is on unix * rtd conda build is on unix * fix rtd * fix rtd * update docs * fix magicmock in rtd docs * remove dead code * reformat docs * fix non-saved file * move oalib.i to main directory * fix build * fix build * fix imports * fix appveyor * fix python install * autopep * bump version * autopep * fix appveyor; cleanup code * fix rtd * remove pylint errors * fix rtd * cleanup code * cleanup code * disable pylint check
eendebakpt · Sep 21, 2018 · c0b3cb7 · c0b3cb7
1 parent 59066aa
commit c0b3cb7
Show file tree

Hide file tree

Showing 43 changed files with 4,092 additions and 2,854 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -2,11 +2,11 @@ build:
   image: latest
 
 python:
-  version: 3.5
+  version: 3.6
   setup_py_install: true
 
 requirements_file: docs/rtd-requirements.txt
 
 # needed to get swig to install
-#conda:
-#  file: rtd-condalist.yml
+conda:
+  file: docs/rtd-condalist.yml
diff --git a/Doxyfile b/Doxyfile
diff --git a/appveyor.yml b/appveyor.yml
@@ -91,7 +91,6 @@ install:
   # pip will build them from source using the MSVC compiler matching the
   # target Python version and architecture
   - "%CMD_IN_ENV% pip install wheel"
-  #- "%WITH_COMPILER% pip install twine"
 
   # Now that wheel has been installed, check to see if a numpy wheel has been
   # made yet. If it hasn't, compile it and put it in C:\tmp.
@@ -114,8 +113,9 @@ install:
   - "%CMD_IN_ENV36% pip install matplotlib"
   - "%CMD_IN_ENV36% jupyter --version"
   - "%CMD_IN_ENV36% jupyter kernelspec list"
-  #- IF %ispython36% == True jupyter --version
-  #- IF %ispython36% == True jupyter kernelspec list
+
+  # lint the code
+  - "%CMD_IN_ENV36% pip install pylint"
 
   # https://chocolatey.org, --allow-empty-checksums
   - cinst -y swig
@@ -128,7 +128,9 @@ build_script:
 
 test_script:
    - "%CMD_IN_ENV% %PYTHON%/python setup.py test"
+   - "%CMD_IN_ENV% %PYTHON%/python -c \"import oapackage; print(oapackage)\""
    - "%CMD_IN_ENV% %PYTHON%/python setup.py install"
+   - "%CMD_IN_ENV% %PYTHON%/python -c \"import oapackage; print(oapackage)\""
    # only run nbconvert for python3.6
    - "%CMD_IN_ENV36% jupyter nbconvert --to notebook --execute  docs/examples/example_alan.ipynb "
    - "%CMD_IN_ENV36% jupyter nbconvert --to notebook --execute  docs/examples/example_oa_files.ipynb "
@@ -142,15 +144,15 @@ test_script:
    - "%CMD_IN_ENV36% jupyter nbconvert --to notebook --execute  docs/examples/example_pareto.ipynb "
    - "%CMD_IN_ENV36% jupyter nbconvert --to notebook --execute  docs/examples/example_designs.ipynb "
 
+   #- "%CMD_IN_ENV36% pylint oapackage --errors-only"
+
 after_test:
   - "%CMD_IN_ENV% %PYTHON%/python setup.py bdist_wheel bdist_wininst"
   - ps: "ls dist"
 
 artifacts:
   - path: dist\*
     name: binaries
-#  - path: '**\oalib_wrap.cpp'
-#    name: swigwrapper
 
 #on_success:
 #  - TODO: upload the content of dist/*.whl to a public wheelhouse

diff --git a/docs/_static/oalogo.png b/docs/_static/oalogo.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -38,14 +38,22 @@ class Mock(MagicMock):
         def __getattr__(cls, name):
             return MagicMock()
 
-    MOCK_MODULES = ['oalib']
+    MOCK_MODULES = ['_oalib']
     sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
+    print('##############################')
+    print('current directory: %s' % os.getcwd())
+    print(os.listdir())
+    print('##############################')   
+    sys.path.append('.')
+    print('##############################')
 
 if rtd:
-    subprocess.call('cd ../; doxygen Doxyfile', shell=True)
+    subprocess.call('cd ../; doxygen Doxyfile; python doxy2swig.py docs/xml/index.xml oadoxy.i', shell=True)
 else:
-    subprocess.call('cd ../; doxygen Doxyfile', shell=True)
+    print('executing doxygen')
+    r=subprocess.call('cd ../; doxygen Doxyfile', shell=True)
+    print('executing doxygen done')
 
 #%%
 # -- General configuration ------------------------------------------------

diff --git a/docs/cppdocs/Doptim.rst b/docs/cppdocs/Doptim.rst
@@ -0,0 +1,5 @@
+Interface for D-optimal designs
+===============================
+
+.. doxygenfile:: Deff.h
+
diff --git a/docs/cppdocs/arraytools.rst b/docs/cppdocs/arraytools.rst
@@ -0,0 +1,5 @@
+Interface for array tools
+=========================
+
+.. doxygenfile:: arraytools.h
+
diff --git a/docs/cppdocs/conference.rst b/docs/cppdocs/conference.rst
@@ -0,0 +1,5 @@
+Interface for conference designs
+================================
+
+.. doxygenfile:: conference.h
+
diff --git a/docs/cppdocs/evenodd.rst b/docs/cppdocs/evenodd.rst
@@ -0,0 +1,4 @@
+Interface for even-odd designs
+==============================
+
+.. doxygenfile:: evenodd.h
diff --git a/docs/cppdocs/graphtools.rst b/docs/cppdocs/graphtools.rst
@@ -0,0 +1,4 @@
+Interface for graph tools
+=========================
+
+.. doxygenfile:: graphtools.h
diff --git a/docs/cppdocs/lmc.rst b/docs/cppdocs/lmc.rst
@@ -0,0 +1,5 @@
+Interface for LMC normal forms
+==============================
+
+.. doxygenfile:: lmc.h
+
diff --git a/docs/cppdocs/md5.rst b/docs/cppdocs/md5.rst
@@ -0,0 +1,4 @@
+Interface for MD5 sums
+======================
+
+.. doxygenfile:: md5.h
diff --git a/docs/cppdocs/pareto.rst b/docs/cppdocs/pareto.rst
@@ -0,0 +1,4 @@
+Interface for Pareto optimality
+===============================
+
+.. doxygenfile:: pareto.h
diff --git a/docs/cpplib.rst b/docs/cpplib.rst
@@ -0,0 +1,14 @@
+C++ library
+===========
+
+
+The full documentation for the C++ library can be build from the source code using [doxygen](http://www.doxygen.nl/).
+For convenience we provide links the main functions on this page.
+
+.. toctree::
+       :maxdepth: 2
+       :titlesonly:
+       :glob:
+
+       cppdocs/*
+
diff --git a/docs/data.rst b/docs/data.rst
@@ -23,38 +23,41 @@ Data structures
 The package contains several data structures. Here we describe the main
 structures and their use.
 
- ``array_link``
+  :meth:`~oapackage.oalib.array_link`
     The structure containing an orthogonal array is called the
-    `array_link` structure. Lists of arrays are stored in the
-    `arraylist_t` object, which as a `std::deque` container.
+    :meth:`~oapackage.oalib.array_link` structure. Lists of arrays are stored in the
+    :meth:`~oapackage.oalib.arraylist_t` object, which is implemented as a :code:`std::deque` container.
 
-  ``arrayfile_t``
+  :meth:`~oapackage.oalib.arrayfile_t`
     This is an object that allows for reading and writing of arrays to
     disk.
 
-  ``arraydata_t``
+  :meth:`~oapackage.oalib.arraydata_t`
     The structure describing a certain class of orthogonal arrays or
-    designs.
+    optimal designs.
 
-  ``array_transformation_t``
+  :meth:`~oapackage.oalib.conference_t`
+    The structure describing a certain class of conference designs.
+
+  :meth:`~oapackage.oalib.array_transformation_t`
     This describes a transformation of an orthogonal array. This includes the row-,
     column- and level-permutations.
 
-  ``conference_transformation_t``
+  :meth:`~oapackage.oalib.conference_transformation_t`
     This describes a transformation of an array. This includes the row-,
     column- and level-permutations.
 
 Representing arrays
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 The structure containing an orthogonal array is called the
 :py:class:`~oalib.array_link` structure. It consists of a specified number of rows and
-columns, the data (integer values) and an index.
+columns, the data (integer valued) and an index.
 
-In the Python interface the arraylink object can be indexed just as
-normal arrays. It is also possible to return a Numpy array. The
-`array\_link` object implements to Python array interface, so most
-opertations from packages such as Numpy work on the `array\_link`
+In the Python interface the :meth:`array_link` object can be indexed just as
+normal arrays. It is also possible to convert to a Numpy array. The
+:meth:`~oapackage.oalib.array_link` object implements to Python array interface, so most
+opertations from packages such as Numpy work on the :code:`array_link`
 object.
 
 .. code-block:: python
@@ -73,11 +76,12 @@ object.
 The C++ class is:
 
 .. doxygenstruct:: array_link
-    :members:
+    :outline:
+    :no-link:
 
 
 Reading and writing arrays
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 Reading and writing arrays to disk can be done with the `arrayfile\_t`
 class. For example:
@@ -178,11 +182,11 @@ the file format see Section :ref:`File formats`. The header of the
     }
 
 Array transformations
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 Transformations of (orthogonal) arrays consist of row permutations,
 level permutations and level transformations. A transformation is
-represented by the `array\_transformation\_t` object.
+represented by the :meth:`~oapackage.oalib.array_transformation_t` object.
 
 For a given transformation the column permutations are applied first,
 then the level permutations and finally the row permutations. The level-
@@ -233,9 +237,9 @@ and column permutations are not commutative.
         ...
 
 Classes of arrays
-~~~~~~~~~~~~~~~~~
+-----------------
 
-The :code:`arraydata_t` object represents data about a class of orthogonal
+The :meth:`~oapackage.oalib.arraydata_t` object represents data about a class of orthogonal
 arrays, e.g. the class :math:`{\operatorname{OA}(N; t; s^k)}`.
 
 .. code-block:: c++
@@ -277,7 +281,7 @@ format. There is a text format with is easily readable by humans and a
 binary format with is faster to process and memory efficient.
 
 Plain text array files
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 Arrays are stored in plain text files with extension .oa. The first line
 contains the number of columns, the number of rows and the number of
@@ -397,9 +401,11 @@ These are:
 
 `oaanalyse`
     Calculates various statistics of arrays in a file. The statistics
-    are described in section `Statistical properties of an array`_.
-
+    are described in section :ref:`Properties of designs`.
 
-.. |image| image:: images/oaimage-18_2-3-3-3-3-3-n17.png
 
+.. figure:: images/oaimage-18_2-3-3-3-3-3-n17.png
+   :alt: alternate text
+   :align: center
 
+   Orthogonal array in :math:`\mathrm{OA}(18, 2 3^a, 2)`
diff --git a/docs/examplenotebooks.rst b/docs/examplenotebooks.rst
@@ -12,8 +12,8 @@ The example Jupyter notebooks can be found on github https://github.com/eendebak
     :glob:
 
     examples/example_oapackage.ipynb
-    examples/example_oa_files.ipynb
     examples/example_designs.ipynb
+    examples/example_oa_files.ipynb
     examples/example_design_generation.ipynb
     examples/example_optimal_orthogonal_arrays.ipynb
     examples/example_generation_optimal_designs.ipynb

diff --git a/docs/generation.rst b/docs/generation.rst
@@ -33,8 +33,8 @@ The main functions for array extension are the following:
         arraylist_t & extend_arraylist(arraylist_t & alist, arraydata_t &fullad, 
                     OAextend const &oaextendoptions);
 
-Here :code:`arraydata_t` is the structure describing the type of arrays and
-:code:`OAextend` contains various options for the algorithm.
+Here :meth:`~oapackage.oalib.arraydata_t` is the structure describing the type of arrays and
+:meth:`~oapackage.oalib.OAextend` contains various options for the algorithm.
 
 A typical session could be:
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -11,7 +11,7 @@ optimal designs and conference designs.
 
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    oapackage-intro
@@ -20,7 +20,12 @@ optimal designs and conference designs.
    generation
    normalform
    properties
-   references
+   cpplib
+   references   
+..   cppdocs/conference.rst
+   cppdocs/Doptim.rst
+   cppdocs/lmc.rst
+   
    
 Indices and tables
 ==================

diff --git a/docs/normalform.rst b/docs/normalform.rst
@@ -22,35 +22,65 @@ to create normal forms of a specific form.
 Reduction to LMC normal form
 ----------------------------
 
-Based on theory from `Complete enumeration of pure‐level and mixed‐level orthogonal arrays, Schoen et al. <https://onlinelibrary.wiley.com/doi/abs/10.1002/jcd.20236>`_.
-
-.. code-block:: c++
-   :caption: Reduction to normal form
-
-    /// reduce an array to canonical form using delete-1-factor ordering
-    array_link reduceLMCform(const array_link &al);
+Based on theory from `Complete enumeration of pure‐level and mixed‐level orthogonal arrays, Schoen et al. <https://onlinelibrary.wiley.com/doi/abs/10.1002/jcd.20236>`_ we can reduce
+orthogonal arrays to LMC normal form. The C++ function to perform reduction is
+
+.. doxygenfunction:: reduceLMCform(const array_link&)
+
+.. comment
+    .. admonition:: C++ block
+    
+        .. doxygenfunction:: reduceLMCform(const array_link&)
+
+    .. sidebar:: Sidebar Title
+        :subtitle: Optional Sidebar Subtitle
+    
+        Subsequent indented lines comprise
+        the body of the sidebar, and are
+        interpreted as body elements.
+
+
+    
+    .. topic:: C++ code
+    
+        .. doxygenfunction:: reduceLMCform(const array_link&)
+    
+    .. code-block:: c++
+       :caption: Reduction to normal form
+    
+    
+        /// reduce an array to canonical form using LMC ordering
+        array_link reduceLMCform(const array_link &al);
 
 Reduction to delete-one-factor projection form
 ----------------------------------------------
 
+The canonical form is described in `A canonical form for non-regular arrays based on generalized word length pattern values of delete-one-factor projections <https://econpapers.repec.org/paper/antwpaper/2014007.htm>`_
+:cite:`EendebakDOF`.
 
-The canonical form is described in `A canonical form for non-regular arrays based on generalized word length pattern values of delete-one-factor projections <https://econpapers.repec.org/paper/antwpaper/2014007.htm>`_.
-An example with the methods is `Example code for delete-one-factor projections` which can be found
+An example with the methods is :ref:`Example code for delete-one-factor projections` which can be found
 in the example notebooks section.
 
-.. code-block:: c++
-   :caption: C++ interface to delete-one-factor projection form
 
-    /// reduce an array to canonical form using delete-1-factor ordering
-    array_link reduceDOPform(const array_link &al);
+The C++ interface to delete-one-factor projection form is:
 
+.. doxygenfunction:: reduceDOPform(const array_link&)
+
+.. comment
+    .. code-block:: c++
+       :caption: C++ interface to delete-one-factor projection form
+    
+        /// reduce an array to canonical form using delete-1-factor ordering
+        array_link reduceDOPform(const array_link &al);
+    
 
 Reduction using graph isomorphisms
 ----------------------------------
 
-To reduce a general graph to Nauty canonical form one can use ``reduceNauty``. For orthogonal arrays we can
+To reduce a general graph to Nauty canonical form one can use :py:meth:`~oapackage.oalib.reduceGraphNauty`. For orthogonal arrays we can
 encode the array structure as a graph. The reduction can then be done
-with ``reduceOAnauty``.
+with :py:meth:`~oapackage.oalib.reduceOAnauty`.
+
 
 .. code-block:: python
    :caption: Reduce a design to normal form using Nauty