Merge pull request #558 from wd15/docker

Use Nix to build Docker instance

DOCKER.md

@@ -0,0 +1,47 @@
+# Run PyMKS in a Docker Instance
+
+## Install Docker
+
+Install Docker and run the Daemon. See
+https://docs.docker.com/engine/install/ for installation
+details. Launch the Daemon if necessary.
+
+    $ sudo service docker start
+
+## Pull the Docker instance
+
+Pull the Docker Instance from Dockerhub
+
+    $ docker pull docker.io/wd15/pymks
+
+## Run the Tests
+
+Run the tests.
+
+    $ docker run -i -t wd15/pymks:latest
+    # python -c "import pymks; pymks.test()"
+
+## Use PyMKS in a Jupyter notebook
+
+    $ docker run -i -t -p 8888:8888 wd15/fipy:latest
+    # jupyter notebook --ip 0.0.0.0 --no-browser
+
+The PyMKS example notebooks are availabe inside the image after
+opening the notebook using http://127.0.0.1:8888.
+
+## Build the Docker instance
+
+Clone this repository and build the instance.
+
+    $ docker load < $(nix-build docker.nix)
+
+or to build and then launch use
+
+    $ docker load < $(nix-build docker.nix) && docker run -p 8888:8888 -it wd15/pymks:latest
+
+## Push the Docker instance
+
+Create the repository in Dockerhub and then push it.
+
+    $ docker login
+    $ docker push docker.io/wd15/pymks

README.md

@@ -1,4 +1,3 @@
-
 # PyMKS Overview
 
 <a href="https://travis-ci.org/materialsinnovation/pymks" target="_blank">
@@ -18,25 +17,26 @@ alt="Travis CI">
 <img src="https://circleci.com/gh/materialsinnovation/pymks.svg?style=shield" alt="Circle CI" height="18">
 </a>
 
-
 PyMKS is an open source, pythonic implementation of the methodologies
 developed under the aegis of Materials Knowledge System (MKS) to build
-salient process-structure-property linkages for materials science applications.
-PyMKS provides for efficient tools for obtaining a digital, uniform grid representation
-of a materials internal structure in terms of its local states, and computing hierarchical
-descriptors of the structure that can be used to build efficient machine
-learning based mappings to the relevant response space.
-
-
-The various materials data analytics workflows developed under the MKS paradigm confirm to
-the data transformation pipeline architecture typical to most Data Science workflows. The workflows
-can be boiled down to a data preprocessing step, followed by a feature generation step (fingerprinting),
-and a model construction step (including hyper parameter optimization). PyMKS, written in a functional
-programming style and supporting distributed computation (multi-core, multi-threaded, cluster), provides
-modular functionalities to address each of these data transformation steps, while maximally leveraging
+salient process-structure-property linkages for materials science
+applications.  PyMKS provides for efficient tools for obtaining a
+digital, uniform grid representation of a materials internal structure
+in terms of its local states, and computing hierarchical descriptors
+of the structure that can be used to build efficient machine learning
+based mappings to the relevant response space.
+
+The various materials data analytics workflows developed under the MKS
+paradigm confirm to the data transformation pipeline architecture
+typical to most Data Science workflows. The workflows can be boiled
+down to a data preprocessing step, followed by a feature generation
+step (fingerprinting), and a model construction step (including hyper
+parameter optimization). PyMKS, written in a functional programming
+style and supporting distributed computation (multi-core,
+multi-threaded, cluster), provides modular functionalities to address
+each of these data transformation steps, while maximally leveraging
 the capabilities of the underlying computing environment.
 
-
 PyMKS consists of tools to compute 2-point statistics, tools for both homogenization
 and localization linkages, and tools for discretizing the microstructure. In addition,
 PyMKS has modules for generating synthetic data sets using conventional numerical
@@ -113,6 +113,20 @@ run
 
 in the base directory.
 
+### Docker
+
+PyMKS has a docker image avilable via
+[docker.io](https://hub.docker.com/repository/docker/wd15/pymks). Assuming
+that you have a working version of Docker, use
+
+    $ docker pull docker.io/wd15/pymks
+    $ docker run -i -t -p 8888:8888 wd15/fipy:latest
+    # jupyter notebook --ip 0.0.0.0 --no-browser
+
+The PyMKS example notebooks are available inside the image after
+opening the Jupyter notebook from http://127.0.0.1:8888. See
+[DOCKER.md](./DOCKER.md) for more details.
+
 ## Optional Packages
 
 Packages that are optional when using PyMKS.
@@ -128,6 +142,16 @@ install when using Nix or Conda, but not when using Pip. See the
 instructions](http://sfepy.org/doc-devel/installation.html) to install
 in your environment.
 
+### GraSPI
+
+GraSPI is a C++ library with a Python interface for creating materials
+descriptors using graph theory. See the [API
+documentation](http://pymks.org/en/stable/API.html#pymks.graph_descriptors)
+for more details. Currently, only the Nix installation builds with
+GraSPI by default To switch off GraSPI when using Nix use,
+
+    $ nix-shell --arg withGraspi false
+
 ## Testing
 
 To test a PyMKS installation use

docker.nix

@@ -0,0 +1,86 @@
+# View DOCKER.md to see how to use this
+
+{
+  tag ? "20.09",
+  withSfepy ? true,
+  withGraspi ? true,
+  graspiVersion ? "59f6a8a2e1ca7c8744a4e37701b919131efb2f45"
+}:
+let
+  pkgs = import (builtins.fetchTarball "https://github.com/NixOS/nixpkgs/archive/${tag}.tar.gz") {};
+  pypkgs = pkgs.python3Packages;
+  pymks = pypkgs.callPackage ./default.nix {
+    sfepy=(if withSfepy then pypkgs.sfepy else null);
+    graspi=(if withGraspi then graspi else null);
+  };
+  graspisrc = builtins.fetchTarball "https://github.com/owodolab/graspi/archive/${graspiVersion}.tar.gz";
+  graspi = pypkgs.callPackage "${graspisrc}/default.nix" {};
+
+  lib = pkgs.lib;
+  USER = "main";
+
+  from_directory = dir: (lib.mapAttrsToList (name: type:
+    if type == "directory" || (lib.hasSuffix "~" name) then
+      null
+    else
+      dir + "/${name}"
+  ) (builtins.readDir dir));
+
+  ## files to copy into the user's home area in container
+  files_to_copy = [ ] ++ (lib.remove null (from_directory ./notebooks));
+
+  ## functions necessary to copy files to USER's home area
+  ## is there an easier way???
+  filetail = path: lib.last (builtins.split "(/)" (toString path));
+  make_cmd = path: "cp ${path} ./home/${USER}/${filetail path}";
+  copy_cmd = paths: builtins.concatStringsSep ";\n" (map make_cmd paths);
+
+  python-env = pkgs.python3.buildEnv.override {
+    ignoreCollisions = true;
+    extraLibs = with pypkgs; [
+      pymks
+      ipywidgets
+    ] ++ pymks.propagatedBuildInputs;
+  };
+in
+  pkgs.dockerTools.buildImage {
+    name = "wd15/pymks";
+    tag = "latest";
+
+    contents = [
+      python-env
+      pkgs.bash
+      pkgs.busybox
+      pkgs.coreutils
+      pkgs.openssh
+      pkgs.bashInteractive
+    ];
+
+    runAsRoot = ''
+      #!${pkgs.stdenv.shell}
+      ${pkgs.dockerTools.shadowSetup}
+      groupadd --system --gid 65543 ${USER}
+      useradd --system --uid 65543 --gid 65543 -d / -s /sbin/nologin ${USER}
+    '';
+
+    extraCommands = ''
+      mkdir -m 1777 ./tmp
+      mkdir -m 777 -p ./home/${USER}
+      # echo 'extra commands'
+      # pwd
+      # cp -r notebooks ./home/${USER}/
+    '' + copy_cmd files_to_copy;
+
+    config = {
+      Cmd = [ "bash" ];
+      User = USER;
+      Env = [
+        "OMPI_MCA_plm_rsh_agent=${pkgs.openssh}/bin/ssh"
+        "HOME=/home/${USER}"
+      ];
+      WorkingDir = "/home/${USER}";
+      Expose = {
+        "8888/tcp" = {};
+      };
+    };
+  }

pymks/fmks/graspi.py

@@ -163,7 +163,6 @@ def graph_descriptors(data, delta_x=1.0, periodic_boundary=True):
     ...                   [0, 1, 0],
     ...                   [0, 1, 0]]])
     >>> actual = graph_descriptors(data)
-    >>> actual.to_csv('out.csv')
 
     ``graph_descriptors`` returns a data frame.