Merge pull request #548 from beyucel/HowToNotebook

How to Notebook for new users

doc/EXAMPLES.rst

@@ -12,6 +12,7 @@ Start with the following notebooks if you are new to PyMKS.
    :maxdepth: 2
 
    rst/notebooks/intro.ipynb
+   rst/notebooks/intro_parallel.ipynb
    rst/notebooks/checkerboard.ipynb
 
 Homogenization

doc/requirements.txt

@@ -5,10 +5,11 @@ toolz
 dask
 matplotlib
 scikit-learn
-nbsphinx==0.5.1
+nbsphinx
 m2r2
 Deprecated
 sphinx-jinja
 alabaster
 IPython
+importlib-metadata==3.10.1
 # require pandoc which is a haskell package

pymks/fmks/data/multiphase.py

@@ -114,8 +114,8 @@ def np_generate(grain_size, volume_fraction, percent_variance, x_blur):
 
 @curry
 def generate_multiphase(
-    shape, grain_size, volume_fraction, chunks=-1, percent_variance=0.0
-):
+    shape, grain_size, volume_fraction, chunks=-1, percent_variance=0.0, seed=None
+):  # pylint: disable=too-many-arguments
     """Constructs microstructures for an arbitrary number of phases
     given the size of the domain, and relative grain size.
 
@@ -126,6 +126,7 @@ def generate_multiphase(
       chunks (int): chunks_size of the first
       percent_variance (float): the percent variance for each value of
         volume_fraction
+      seed (int): set the seed value, default is no seed
 
     Returns:
       A dask array of random-multiphase microstructures
@@ -136,28 +137,52 @@ def generate_multiphase(
     >>> x_tru = np.array([[[0, 0, 0],
     ...                    [0, 1, 0],
     ...                    [1, 1, 1]]])
-    >>> da.random.seed(10)
+
     >>> x = generate_multiphase(
     ...     shape=(1, 3, 3),
     ...     grain_size=(1, 1),
-    ...     volume_fraction=(0.5, 0.5)
+    ...     volume_fraction=(0.5, 0.5),
+    ...     seed=10
     ... )
     >>> print(x.shape)
     (1, 3, 3)
-    >>> print(x.chunks)
-    ((1,), (3,), (3,))
+
     >>> assert np.allclose(x, x_tru)
 
+    If `chunks` is not set a Numpy array is returned.
+
+    >>> type(x)
+    <class 'numpy.ndarray'>
+
+    If `chunks` is defined a Dask array is returned.
+
+    >>> x = generate_multiphase(
+    ...     shape=(2, 3, 3),
+    ...     grain_size=(1, 1),
+    ...     volume_fraction=(0.5, 0.5),
+    ...     chunks=1
+    ... )
+
+    >>> print(x.chunks)
+    ((1, 1), (3,), (3,))
+
     """
 
+    if seed is not None:
+        da.random.seed(seed)
+        np.random.seed(seed)
+
     if len(grain_size) + 1 != len(shape):
         raise RuntimeError("`shape` should be of length `len(grain_size) + 1`")
 
     if not np.allclose(np.sum(volume_fraction), 1):
         raise RuntimeError("The terms in the volume fraction list should sum to 1")
 
-    return map_blocks(
-        np_generate(grain_size, volume_fraction, percent_variance),
-        da.random.random(shape, chunks=(chunks,) + shape[1:]),
-        dtype=np.int64,
+    return pipe(
+        map_blocks(
+            np_generate(grain_size, volume_fraction, percent_variance),
+            da.random.random(shape, chunks=(chunks,) + shape[1:]),
+            dtype=np.int64,
+        ),
+        lambda x: x if chunks > 0 else x.compute(),
     )

pymks/fmks/plot.py

@@ -6,17 +6,20 @@
 
 
 @curry
-def _plot_ax(axis, arrs, titles, cmap):
+def _plot_ax(axis, arrs, titles, cmap, showticks):
     if hasattr(axis.get_subplotspec(), "colspan"):
         col_num = axis.get_subplotspec().colspan.start  # pragma: no cover
     else:
         col_num = axis.colNum  # pragma: no cover
-    axis.set_xticks(())
-    axis.set_yticks(())
+    if not showticks:
+        axis.set_xticks(())
+        axis.set_yticks(())
     axis.set_title(titles[col_num])
+    extent_ = lambda dim: (-arrs[col_num].shape[dim] / 2, arrs[col_num].shape[dim] / 2)
     return axis.imshow(
         arrs[col_num],
         interpolation="none",
+        extent=extent_(1) + extent_(0),
         vmin=numpy.min(numpy.vstack(arrs)),
         vmax=numpy.max(numpy.vstack(arrs)),
         cmap=cmap,
@@ -30,7 +33,9 @@ def _colorbar(fig, axis, image):
     fig.colorbar(image, cax=axis)
 
 
-def plot_microstructures(*arrs, titles=(), cmap=None, colorbar=True, figsize_weight=4):
+def plot_microstructures(
+    *arrs, titles=(), cmap=None, colorbar=True, showticks=False, figsize_weight=4
+):
     """Plot a set of microstructures
 
     Args:
@@ -51,7 +56,9 @@ def plot_microstructures(*arrs, titles=(), cmap=None, colorbar=True, figsize_wei
         titles = (titles,)
     if len(titles) < len(arrs):
         titles = titles + ("",) * (len(arrs) - len(titles))
-    plots = list(fmap(_plot_ax(arrs=arrs, titles=titles, cmap=cmap), axs))
+    plots = list(
+        fmap(_plot_ax(arrs=arrs, titles=titles, cmap=cmap, showticks=showticks), axs)
+    )
     if colorbar:
         _colorbar(
             fig, fig.add_axes([1.0, 0.05, 0.05, 0.9]), plots[0],

pymks/fmks/tests/test_multiphase.py

@@ -5,7 +5,6 @@
 import numpy as np
 
 import pytest
-import dask.array as da
 
 from pymks.fmks.data.multiphase import generate_multiphase, np_generate
 from pymks.datasets.microstructure_generator import MicrostructureGenerator
@@ -15,9 +14,13 @@ def test_chunking():
     """Test that the generated microstructue is chunked correctly
 
     """
-    da.random.seed(10)
+
     data = generate_multiphase(
-        shape=(5, 11, 11), grain_size=(3, 4), volume_fraction=(0.5, 0.5), chunks=2
+        shape=(5, 11, 11),
+        grain_size=(3, 4),
+        volume_fraction=(0.5, 0.5),
+        chunks=2,
+        seed=10,
     )
     assert data.shape == (5, 11, 11)
     assert data.chunks == ((2, 2, 1), (11,), (11,))
@@ -26,19 +29,17 @@ def test_chunking():
 def test_2d():
     """Regression test for microstructure phases
     """
-    da.random.seed(10)
     data = generate_multiphase(
-        shape=(1, 4, 4), grain_size=(4, 4), volume_fraction=(0.5, 0.5)
+        shape=(1, 4, 4), grain_size=(4, 4), volume_fraction=(0.5, 0.5), seed=10
     )
     assert np.allclose(data, [[[0, 0, 0, 0], [1, 0, 1, 1], [1, 1, 0, 1], [1, 0, 0, 0]]])
 
 
 def test_1d():
     """Test that 1D works
     """
-    da.random.seed(10)
     data = generate_multiphase(
-        shape=(1, 10), grain_size=(4,), volume_fraction=(0.5, 0.5)
+        shape=(1, 10), grain_size=(4,), volume_fraction=(0.5, 0.5), seed=10
     )
     assert np.allclose(data, [0, 0, 0, 0, 1, 0, 1, 1, 1, 1])
 
@@ -48,9 +49,8 @@ def test_grain_size():
     Test incompatible grain_size and shape
     """
     with pytest.raises(RuntimeError) as excinfo:
-        da.random.seed(10)
         generate_multiphase(
-            shape=(1, 10, 10), grain_size=(4,), volume_fraction=(0.5, 0.5)
+            shape=(1, 10, 10), grain_size=(4,), volume_fraction=(0.5, 0.5), seed=10
         )
     assert str(excinfo.value) == "`shape` should be of length `len(grain_size) + 1`"
 
@@ -59,9 +59,8 @@ def test_volume_fraction():
     """Test incoherent volume_fraction
     """
     with pytest.raises(RuntimeError) as excinfo:
-        da.random.seed(10)
         generate_multiphase(
-            shape=(1, 10), grain_size=(2,), volume_fraction=(0.4, 0.4, 0.4)
+            shape=(1, 10), grain_size=(2,), volume_fraction=(0.4, 0.4, 0.4), seed=10
         )
     assert str(excinfo.value) == "The terms in the volume fraction list should sum to 1"
 
@@ -73,12 +72,12 @@ def test_3d():
     different.
 
     """
-    da.random.seed(10)
     data = generate_multiphase(
         shape=(5, 5, 5, 5),
         grain_size=(1, 5, 1),
         volume_fraction=(0.3, 0.3, 0.4),
         chunks=2,
+        seed=10,
     )
     assert data.chunks == ((2, 2, 1), (5,), (5,), (5,))
     assert np.allclose(