Merge pull request #176 from Libensemble/develop

Develop

.flake8

@@ -0,0 +1,37 @@
+[flake8]
+ignore = 
+        # Not worrying about line length for now
+        E501,
+        # Not worrying about spaces around arithmetic operations
+        E226
+        # Allow variables O, l, etc
+        E741
+        # Line breaks before unary operators are okay
+        W503
+        # Line breaks after unary operators are okay
+        W504
+        # Lambda expressions are okay
+        E731
+exclude = 
+        # Don't need to check .git
+        .git,
+        # Largely autogenerated
+        docs/conf.py
+        # Keeping bad python format to match PETSc source code 
+        libensemble/sim_funcs/chwirut1.py
+        examples/sim_funcs/chwirut1.py
+        # This is not implemented yet
+        controller_tests/test_jobcontroller_manager_poll.py
+        # Not checking these scripts yet
+        postproc_scripts
+        # Do not check these experimental tests
+        balsam_tests
+
+# Note that you can use wildcard exceptions with something such as
+# libensemble/libensemble/tests/regression_tests/*:F401
+per-file-ignores =
+        # init needs to import the logger.
+        libensemble/__init__.py:F401
+        # Need to turn of matching probes (before other imports) on some
+        # systems/versions of MPI:
+        libensemble/tests/standalone_tests/mpi_launch_test/create_mpi_jobs.py:E402 

.readthedocs.yml

@@ -2,6 +2,6 @@ conda:
     file: conda/environment.yml
 
 python:
-    version: 3.5
+    version: 3.6
     pip_install: true
-
+    setup_py_install: true

.style.yapf

@@ -0,0 +1,17 @@
+[style]
+based_on_style = pep8
+spaces_before_comment = 2
+INDENT_WIDTH = 4
+SPLIT_BEFORE_DOT = True
+COLUMN_LIMIT = 79
+SPLIT_BEFORE_NAMED_ASSIGNS = False
+SPACE_BETWEEN_ENDING_COMMA_AND_CLOSING_BRACKET = False
+ALLOW_SPLIT_BEFORE_DEFAULT_OR_NAMED_ASSIGNS = False 
+ALLOW_SPLIT_BEFORE_DICT_VALUE = False
+DEDENT_CLOSING_BRACKETS = False
+EACH_DICT_ENTRY_ON_SEPARATE_LINE = True
+INDENT_DICTIONARY_VALUE = True
+NO_SPACES_AROUND_SELECTED_BINARY_OPERATORS = //,*,+,-,/
+SPLIT_BEFORE_CLOSING_BRACKET = False
+# This last one doesn't quite work yet.
+SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN = False

.travis.yml

@@ -2,7 +2,6 @@ language: python
 sudo: required
 dist: xenial
 python:
-  - 2.7
   - 3.4
   - 3.5
   - 3.6
@@ -18,9 +17,9 @@ env:
     - MPI=mpich
     #- MPI=openmpi
 
-matrix:
-  allow_failures:
-    - env: MPI=openmpi
+#matrix:
+#  allow_failures:
+#    - env: MPI=openmpi
 
 addons:
   apt:
@@ -56,7 +55,7 @@ install:
   - conda install $MPI
   - conda install --no-update-deps scipy # includes numpy
   - conda install --no-update-deps mpi4py
-  - conda install --no-update-deps petsc4py petsc
+  - conda install petsc4py petsc
   - conda install --no-update-deps nlopt
   # pip install these as the conda installs downgrade pytest on python3.4
   - pip install pytest

CONTRIBUTING.rst

@@ -0,0 +1,63 @@
+Contributing
+============
+
+Contributions may be made via Github pull request to:
+
+    https://github.com/Libensemble/libensemble
+
+libEnsemble uses the Gitflow model. Contributors should branch from, and
+make pull requests to, the develop branch. The master branch is used only
+for releases. Code should pass flake8 tests, allowing for the exceptions
+given in the ".flake8" configuration file in the project directory.
+
+Issues can be raised at:
+
+    https://github.com/Libensemble/libensemble/issues
+
+Issues may include reporting bugs or suggested features. Administrators
+will add issues, as appropriate, to the project board at:
+
+    https://github.com/Libensemble/libensemble/projects
+
+By convention, user branch names should have a <type>/<name> format, where
+example types are feature, bugfix, testing, docs and experimental.
+Administrators may take a hotfix branch from the the master, which will be
+merged into master (as a patch) and develop. Administrators may also take a
+release branch off develop and merge into master and develop for a release.
+Most branches should relate to an issue.
+
+When a branch closes a related issue, the pull request message should include
+the phrase "Closes #N" where N is the issue number. This will automatically
+close out the issues when they are pulled into the default branch (currently
+master).
+
+libEnsemble is distributed under a 3-clause BSD license (see LICENSE).  The
+act of submitting a pull request (with or without an explicit
+Signed-off-by tag) will be understood as an affirmation of the
+following:
+
+  Developer's Certificate of Origin 1.1
+
+  By making a contribution to this project, I certify that:
+
+  (a) The contribution was created in whole or in part by me and I
+      have the right to submit it under the open source license
+      indicated in the file; or
+
+  (b) The contribution is based upon previous work that, to the best
+      of my knowledge, is covered under an appropriate open source
+      license and I have the right under that license to submit that
+      work with modifications, whether created in whole or in part
+      by me, under the same open source license (unless I am
+      permitted to submit under a different license), as indicated
+      in the file; or
+
+  (c) The contribution was provided directly to me by some other
+      person who certified (a), (b) or (c) and I have not modified
+      it.
+
+  (d) I understand and agree that this project and the contribution
+      are public and that a record of the contribution (including all
+      personal information I submit with it, including my sign-off) is
+      maintained indefinitely and may be redistributed consistent with
+      this project or the open source license(s) involved.

README.rst

@@ -1,6 +1,7 @@
-===========
-libEnsemble
-===========
+.. image:: docs/images/libE_logo.png
+  :alt: libEnsemble
+
+|
 
 .. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
    :target: https://travis-ci.org/Libensemble/libensemble
@@ -12,29 +13,58 @@ libEnsemble
    :target: https://libensemble.readthedocs.org/en/latest/
    :alt: Documentation Status
 
+|
+
+====================
+What is libEnsemble?
+====================
+
+libEnsemble is a Python library to coordinate the concurrent evaluation of ensembles of computations.
+Designed with flexibility in mind, libEnsemble can utilize massively parallel resources to accelerate
+the solution of design, decision, and inference problems.
+
+libEnsemble aims for:
+
+• Extreme scaling
+• Fault tolerance
+• Monitoring/killing jobs (recovers resources)
+• Portability and flexibility
+• Exploitation of persistent data/control flow.
 
-Library for managing ensemble-like collections of computations.
+A more detailed overview can be found in the docs_.
+
+.. _docs:  https://libensemble.readthedocs.org/en/latest/
+
+A visual overview is given in the libEnsemble poster_.
+
+.. _poster:  https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
 
 
 Dependencies
 ------------
 
-* Python_ 2.7, 3.4 or above.
+Required dependencies:
+
+* Python_ 3.4 or above.
+
+* NumPy_
+
+For libEnsemble running with the mpi4py parallelism:
 
 * A functional MPI 1.x/2.x/3.x implementation such as `MPICH
   <http://www.mpich.org/>`_  built with shared/dynamic libraries.
 
 * mpi4py_ v2.0.0 or above
 
-* NumPy_
 
 Optional dependency:
 
 * Balsam_
 
 From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
-is required for running on some supercomputing platforms (eg. Cray XC40);
-platforms which do not support launching jobs on compute nodes.
+is required for running libEnsemble on the compute nodes of some supercomputing
+platforms (eg. Cray XC40); platforms that do not support launching jobs from compute nodes.
+Note that as of v0.5.0, libEnsemble can also be run on the launch nodes using multiprocessing.
 
 The example sim and gen functions and tests require the following dependencies:
 
@@ -60,15 +90,16 @@ produce a file nlopt.py if Python is found on the system.
 Installation
 ------------
 
-You can use pip to install libEnsemble and its dependencies::
+Use pip to install libEnsemble and its dependencies::
 
     pip install libensemble
 
-Libensemble is also available in the Spack_ distribution.
+libEnsemble is also available in the Spack_ distribution.
 
 .. _Spack: https://spack.readthedocs.io/en/latest
 
-The tests and examples can be accessed in the `github <https://github.com/Libensemble/libensemble>`_ repository. A `tarball <https://github.com/Libensemble/libensemble/releases/latest>`_ of the most recent release is also available.
+The tests and examples can be accessed in the `github <https://github.com/Libensemble/libensemble>`_ repository.
+A `tarball <https://github.com/Libensemble/libensemble/releases/latest>`_ of the most recent release is also available.
 
 
 Testing
@@ -112,23 +143,41 @@ Basic Usage
 The examples directory contains example libEnsemble calling scripts, sim
 functions, gen functions, alloc functions and job submission scripts.
 
-See the `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_ for more information.
+See the `user-guide <https://libensemble.readthedocs.io/en/latest/readme.html#basic-usage>`_ for more information.
 
 
 Documentation
 -------------
 
 * http://libensemble.readthedocs.org/
 
+Citing libEnsemble
+------------------
+Please use the following to cite libEnsemble in a publication:
+
+.. code-block:: bibtex
+
+  @techreport{libEnsemble,
+    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and David Bindel},
+    title       = {{libEnsemble} Users Manual},
+    institution = {Argonne National Laboratory},
+    number      = {Revision 0.5.0},
+    year        = {2019},
+    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
+  }
+
 
 Support 
 -------
 
-You can join the libEnsemble mailing list at:
+Join the libEnsemble mailing list at:
 
 * https://lists.mcs.anl.gov/mailman/listinfo/libensemble 
 
 or email questions to:
 
 * libensemble@lists.mcs.anl.gov
 
+or communicate (and establish a private channel, if desired) at:
+
+* https://libensemble.slack.com 

conda/environment.yml

@@ -1,4 +1,3 @@
 dependencies:
- - python==3.5
- - mpi4py
- - numpy
+ - python>=3.6
+

conda/find_mpi.py

@@ -1,11 +1,10 @@
-from __future__ import print_function
 import os
 import mpi4py
 
-path=mpi4py.__path__[0]
+path = mpi4py.__path__[0]
 print("\nmpi4py path found is:", path)
 
-configfile=os.path.join(path,"mpi.cfg")
+configfile = os.path.join(path, "mpi.cfg")
 print("\nShowing config file: ", configfile, "\n")
 
 with open(configfile, 'r') as confile_handle:
@@ -14,9 +13,9 @@
 with open(configfile, 'r') as infile:
     for line in infile:
         if line.startswith("mpicc ="):
-           mpi4py_mpicc=line[8:-1]
-           cmd_line=str(mpi4py_mpicc) + ' -v'
-           break
+            mpi4py_mpicc = line[8:-1]
+            cmd_line = str(mpi4py_mpicc) + ' -v'
+            break
 
 print(cmd_line, ":\n")
 os.system(cmd_line)

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
+SPHINXBUILD   = python3 -msphinx
 SPHINXPROJ    = libensemble
 SOURCEDIR     = .
 BUILDDIR      = _build
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)