From 09263b921c2883cc1ac0ebd1112c98db8fe4ce6a Mon Sep 17 00:00:00 2001 From: Daniel Wheeler Date: Thu, 11 Mar 2021 16:31:19 -0500 Subject: [PATCH 1/3] doc: change style of docs to alabaster Change style of docs from bootstrap to alabaster. Clean up and simplify overall. Make the notebooks work correctly as part of the table of contents by including in a rst file rather than using index.ipynb as the main notebook index file. Also, stop using mock to allow solve_fe docs. The solve_fe function can now be imported without sfepy being required so remove all the mock paraphernalia from conf.py. --- README.md | 13 +- doc/API.rst | 12 ++ doc/EXAMPLES.rst | 32 +++- doc/{ => _static}/pymks_logo.ico | Bin doc/{ => _static}/pymks_logo.svg | 0 doc/_templates/navbar.html | 6 - doc/_templates/release.html | 7 + doc/conf.py | 308 +++---------------------------- doc/contents.rst | 12 +- doc/homogenization.rst | 8 - doc/index.rst | 2 + doc/localization.rst | 12 -- doc/pymks_logo.png | Bin 1382 -> 0 bytes doc/requirements.txt | 4 +- doc/spatial_stats.rst | 7 - index.ipynb | 18 +- pymks/fmks/pair_correlations.py | 26 +-- pymks/fmks/plot.py | 2 +- 18 files changed, 115 insertions(+), 354 deletions(-) rename doc/{ => _static}/pymks_logo.ico (100%) rename doc/{ => _static}/pymks_logo.svg (100%) delete mode 100644 doc/_templates/navbar.html create mode 100644 doc/_templates/release.html delete mode 100644 doc/homogenization.rst delete mode 100644 doc/localization.rst delete mode 100644 doc/pymks_logo.png delete mode 100644 doc/spatial_stats.rst diff --git a/README.md b/README.md index d0de0302..254cc0da 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,5 @@ -

-PyMKS logo -

- -

-PyMKS – The Materials Knowledge System in Python -

-

+ +# PyMKS Overview + + + version: {{ release }} + + +

diff --git a/doc/conf.py b/doc/conf.py index a4e99526..4daf6556 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,316 +1,72 @@ -# -*- coding: utf-8 -*- -# -# electrical documentation build configuration file, created by -# sphinx-quickstart on Thu Mar 22 15:47:53 2012. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - import sys import os -import sphinx_bootstrap_theme +import alabaster -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('..')) +html_theme_path = [alabaster.get_path()] +extensions = ['alabaster'] +html_theme = 'alabaster' -# -- General configuration ----------------------------------------------- +sys.path.insert(0, os.path.abspath('..')) -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +root_doc = 'index' -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'sphinx.ext.autosummary', 'sphinx.ext.napoleon', 'nbsphinx', 'm2r2', - 'sphinxcontrib.jinja'] + 'sphinxcontrib.jinja', + 'IPython.sphinxext.ipython_console_highlighting' +] -# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix of source filenames. - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The master toctree document. master_doc = 'contents' -# General information about the project. project = u'pymks' -copyright = u'2015, David Brough' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. - -# Sfepy needs to be completely mocked for the docs as it can't be -# install with pip. - -MOCK_MODULES = [ - 'sfe', - 'sfepy', - 'sfepy.base', - 'sfepy.discrete', - 'sfepy.discrete.fem', - 'sfepy.discrete.conditions', - 'sfepy.terms', - 'sfepy.solvers', - 'sfepy.solvers.ls', - 'sfepy.solvers.nls', - 'sfepy.discrete.fem.periodic', - 'sfepy.mesh', - 'sfepy.mesh.mesh_generators', - 'sfepy.mechanics', - 'sfepy.mechanics.matcoefs', - 'sfepy.base.base' -] - -import mock - -for module in MOCK_MODULES: - sys.modules[module] = mock.Mock() - -# goptions is assigned to so needs to support assignment - -m = mock.MagicMock() -d = dict(key='value') -m.__getitem__.side_effect = d.__getitem__ -sys.modules['sfepy.base.goptions'] = m +copyright = u'2021, Daniel Wheeler' import pymks version = pymks.__version__ -# The full version, including alpha/beta/rc tags. release = pymks.__version__ -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. exclude_patterns = ['_build', '**.ipynb_checkpoints'] autoclass_content = 'both' +pygments_style = 'alabaster.support.Alabaster' -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - - -# -- Options for HTML output --------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -#html_theme = 'sphinxdoc' -html_theme = 'bootstrap' -html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() +html_sidebars = { + '**': [ + 'about.html', + 'release.html', + 'navigation.html', + ] +} -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. html_theme_options = { - 'navbar_title': "PyMKS", - 'navbar_site_name': "More", - 'navbar_links': [ - ("Examples", "rst/index.html", True), - ("API", "API.html", True), - ("Theory", "THEORY.html", True), - ("GitHub", "https://github.com/materialsinnovation/pymks/", True), - ], - 'navbar_pagenav': False, - 'navbar_sidebarrel': False, - 'globaltoc_depth': 2, - 'source_link_position': '', - 'bootswatch_theme': 'cosmo', + 'logo': 'pymks_logo.svg', + 'github_user': 'materialsinnovation', + 'github_repo': 'pymks', + 'github_button': True, + 'sidebar_collapse': True, + 'sidebar_width': '200px', + 'page_width': '1050px', + 'fixed_sidebar': True } -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". html_title = "PyMKS" - -# A shorter title for the navigation bar. Default is the same as html_title. html_short_title = "PyMKS" - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -html_logo = 'pymks_logo.svg' - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -html_favicon = 'pymks_logo.ico' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". +html_favicon = '_static/pymks_logo.ico' html_static_path = ['_static'] - html_css_files = [ 'pymks.css' ] -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. html_additional_pages = {} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. html_show_copyright = False - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. htmlhelp_basename = 'pymksdoc' - -# -- Options for LaTeX output -------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - #'preamble': '', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ('index', 'pymks.tex', u'PyMKS Documentation', - u'David Brough', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'pymks', u'PyMKS Documentation', - [u'David Brough'], 1) -] - -# If true, show URL addresses after external links. -#man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------ - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ('index', 'pymks', u'PyMKS Documentation', - u'David Brough', 'pymks', 'Materials Knowledge Systems in Python', - 'Miscellaneous'), -] - - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -# from recommonmark.parser import CommonMarkParser -# from recommonmark.transform import AutoStructify - -# source_parsers = {'.md' : CommonMarkParser} source_suffix = ['.rst', '.md'] def url_resolver(url): @@ -330,13 +86,6 @@ def url_resolver(url): else: return url -# def setup(app): -# app.add_config_value('recommonmark_config', { -# 'url_resolver': url_resolver, -# 'auto_toc_tree_section': 'Contents', -# }, True) -# app.add_transform(AutoStructify) - import shutil, os, glob rst_directory = 'rst' @@ -348,9 +97,6 @@ def url_resolver(url): files_to_copy = ( 'README.md', - 'LICENSE.md', - 'CITATION.md', - 'index.ipynb', 'notebooks/*.ipynb' ) diff --git a/doc/contents.rst b/doc/contents.rst index 37c6d397..0e1bc5df 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -1,6 +1,6 @@ .. raw:: html - + .. pymks documentation master file, created by sphinx-quickstart on Thu Mar 22 15:47:53 2012. @@ -8,9 +8,11 @@ contain the root `toctree` directive. .. toctree:: - :hidden: - :maxdepth: 0 + :maxdepth: 4 :glob: + :hidden: - rst/*.ipynb - rst/notebooks/*.ipynb + rst/README.md + EXAMPLES.rst + API.rst + THEORY.rst diff --git a/doc/homogenization.rst b/doc/homogenization.rst deleted file mode 100644 index ec34759d..00000000 --- a/doc/homogenization.rst +++ /dev/null @@ -1,8 +0,0 @@ -Homogenization -============== - -.. toctree:: - :maxdepth: 1 - - rst/homogenization_stress_2D.rst - rst/homogenization_fiber_2D.rst \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 627430de..f253eeb4 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,3 +1,5 @@ +:orphan: + .. raw:: html diff --git a/doc/localization.rst b/doc/localization.rst deleted file mode 100644 index 632f4c75..00000000 --- a/doc/localization.rst +++ /dev/null @@ -1,12 +0,0 @@ -Localization -============ - -.. toctree:: - :maxdepth: 1 - - rst/localization_elasticity_2D.rst - rst/localization_elasticity_multiphase_2D.rst - rst/localization_elasticity_3D.rst - rst/filter.rst - rst/localization_cahn_hilliard_2D.rst - rst/localization_cahn_hilliard_Legendre_2D.rst diff --git a/doc/pymks_logo.png b/doc/pymks_logo.png deleted file mode 100644 index b19ff4c8673ae48df32a569413ff46d0695a00eb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1382 zcmV-s1)2JZP)1~XdG)6fU45K*{sSeCA!p@isBHya=hoC=Xuv;jMEO4d28wCLFrOAzuX8 z5A0XrWVWiyAkziD_SXdV+*!S7@^E9qCz>ud!4n;t^EhF7r1_;C|3&)}?xXPtRxT`2 zoWb+2qv781pZ)YtCX37j3bXL&zG+oU9zI)H*9&ok&Z({NHig@YhjexSyRxnuKqHaW zplhNAgEz&j8}Xlvx+176Gd^-7O?1iXZj8M_=Ma68t(xb-) zZI-oOakdS{&~UaQtV z3Q`&0s#Pr&JGaNTWrri>HMYN|>|>BkNgY+w6RIL5qRdNVOD9&Q(1`GO)xu*}tsEB3a5 zOCPXBiMWwx82w(6PooW2gho`|7phuyro8@qwCTF#S-`hibToG#A9l8he z#rKRpU3XPZSA^P*Q|LmPkirM&T4z6Ys=TgaxY3nW*CVDhOPg3Ha9ZGdkC=@^=VVL` z*~x!3j>Tz7HF!lo6k~0Ya7ZO=)c8Ca3|lI`el=E}W9&W^+oO{2Q4<{fJ5W7rdY`Uj;JB|IlW~=knd@c>n+a07*qoM6N<$g5ThWeE`_ The pair correlation is defined as the conditional probability for - the case of the magnitude vector, $||r||_2$, defined by $ g[ d ]$. - $g$ is related to $f$ via the following + the case of the magnitude vector, :math:`||r||_2`, defined by :math:`g[d]`. + :math:`g` is related to :math:`f` via the following transformation. Consider the set, - $ I[d] := \\{ f[r] \\; \\vert \\; ||r||_2 = d \\} $ + :math:`I[d] := \{ f[r] \; \vert \; ||r||_2 = d \}` then - $$ g[d] = \\frac{1}{ | I[ d ] | } \\sum_{f \\in I[ d ]} f $$ + .. math:: + + g[d] = \frac{1}{ | I[ d ] | } \sum_{f \in I[ d ]} f - The $d$ are radii from the center pixel of the domain. They are - automatially calculated if ``interpolate_n`` is ``None``. + The :math:`d` are radii from the center pixel of the domain. They + are automatially calculated if ``interpolate_n`` is ``None``. It's assumed that ``x_data`` is a valid set of two point statistics calculated from the PyMKS correlations module. diff --git a/pymks/fmks/plot.py b/pymks/fmks/plot.py index 9c8af0f3..fdc6bc02 100644 --- a/pymks/fmks/plot.py +++ b/pymks/fmks/plot.py @@ -30,7 +30,7 @@ def plot_microstructures(*arrs, titles=(), cmap=None, colorbar=True, figsize_wei """Plot a set of microstructures Args: - *arrs: any number of 2D arrays to plot + arrs: any number of 2D arrays to plot titles: a sequence of titles with len(*arrs) cmap: any matplotlib colormap From 5911d2c85a7e459267fa2edac438deaaf6b3eacf Mon Sep 17 00:00:00 2001 From: Daniel Wheeler Date: Fri, 12 Mar 2021 15:09:23 -0500 Subject: [PATCH 2/3] refactor: allow solve_fe docs without sfepy Allow solve_fe to display its documentation without having to import sfepy. --- pymks/__init__.py | 16 ++------------ pymks/fmks/data/__init__.py | 31 +++++++++++++++++++++++++++ pymks/fmks/data/elastic_fe.py | 24 ++++----------------- pymks/fmks/tests/test_fe.py | 2 +- pymks/fmks/tests/test_localization.py | 2 +- 5 files changed, 39 insertions(+), 36 deletions(-) diff --git a/pymks/__init__.py b/pymks/__init__.py index a656a81d..dae6fe24 100644 --- a/pymks/__init__.py +++ b/pymks/__init__.py @@ -26,20 +26,8 @@ from .fmks.correlations import TwoPointCorrelation from .fmks.data.checkerboard import generate_checkerboard from .fmks.pair_correlations import paircorr_from_twopoint +from .fmks.data import solve_fe -try: - import sfepy # noqa: F401 -except ImportError: - - def solve_fe(*_, **__): - """Dummy funcion when sfepy unavailable - """ - # pylint: disable=redefined-outer-name, import-outside-toplevel, unused-import - import sfepy # noqa: F401, F811 - - -else: - from .fmks.data.elastic_fe import solve_fe # the following will be deprecated from .mks_localization_model import MKSLocalizationModel @@ -51,7 +39,7 @@ def solve_fe(*_, **__): MKSRegressionModel = MKSLocalizationModel DiscreteIndicatorBasis = PrimitiveBasis ContinuousIndicatorBasis = PrimitiveBasis -# the above will be deprecatec +# the above will be deprecated def test(): diff --git a/pymks/fmks/data/__init__.py b/pymks/fmks/data/__init__.py index e69de29b..89484360 100644 --- a/pymks/fmks/data/__init__.py +++ b/pymks/fmks/data/__init__.py @@ -0,0 +1,31 @@ +"""Functions for generating data +""" +from ..func import curry + + +@curry +def solve_fe(x_data, elastic_modulus, poissons_ratio, macro_strain=1.0, delta_x=1.0): + """Solve the elasticity problem + + Args: + x_data: microstructure with shape (n_samples, n_x, ...) + elastic_modulus: the elastic modulus in each phase + poissons_ration: the poissons ratio for each phase + macro_strain: the macro strain + delta_x: the grid spacing + + Returns: + a dictionary of strain, displacement and stress with stress and + strain of shape (n_samples, n_x, ..., 3) and displacement shape + of (n_samples, n_x + 1, ..., 2) + + """ + from .elastic_fe import _solve_fe # pylint: disable=import-outside-toplevel + + return _solve_fe( + x_data, + elastic_modulus, + poissons_ratio, + macro_strain=macro_strain, + delta_x=delta_x, + ) diff --git a/pymks/fmks/data/elastic_fe.py b/pymks/fmks/data/elastic_fe.py index 48285ec3..cb2d3b1b 100644 --- a/pymks/fmks/data/elastic_fe.py +++ b/pymks/fmks/data/elastic_fe.py @@ -12,7 +12,7 @@ >>> X = np.zeros((1, 3, 3), dtype=int) >>> X[0, :, 1] = 1 ->>> strain = solve_fe( +>>> strain = _solve_fe( ... X, ... elastic_modulus=(1.0, 10.0), ... poissons_ratio=(0., 0.), @@ -43,7 +43,7 @@ ... [1, 0, 0, 1]]]) >>> n_samples, N, N = X.shape >>> macro_strain = 0.1 ->>> displacement = solve_fe( +>>> displacement = _solve_fe( ... X, ... elastic_modulus=(10.0, 1.0), ... poissons_ratio=(0.3, 0.3), @@ -80,7 +80,7 @@ >>> print(X.shape) (2, 4, 4) >>> x_data = da.from_array(X, chunks=(1, 4, 4)) ->>> out = solve_fe(x_data, +>>> out = _solve_fe(x_data, ... elastic_modulus=(10.0, 1.0), ... poissons_ratio=(0.3, 0.3), ... macro_strain=macro_strain)['displacement'] @@ -145,23 +145,7 @@ @curry -def solve_fe(x_data, elastic_modulus, poissons_ratio, macro_strain=1.0, delta_x=1.0): - """Solve the elasticity problem - - Args: - x_data: microstructure with shape (n_samples, n_x, ...) - elastic_modulus: the elastic modulus in each phase - poissons_ration: the poissons ratio for each phase - macro_strain: the macro strain - delta_x: the grid spacing - - Returns: - a dictionary of strain, displacement and stress with stress and - strain of shape (n_samples, n_x, ..., 3) and displacement shape - of (n_samples, n_x + 1, ..., 2) - - """ - +def _solve_fe(x_data, elastic_modulus, poissons_ratio, macro_strain=1.0, delta_x=1.0): def solve_one_sample(property_array): return pipe( get_fields(property_array.shape[:-1], delta_x), diff --git a/pymks/fmks/tests/test_fe.py b/pymks/fmks/tests/test_fe.py index 9d4e4832..a6d388ef 100644 --- a/pymks/fmks/tests/test_fe.py +++ b/pymks/fmks/tests/test_fe.py @@ -4,7 +4,7 @@ import pytest import numpy as np from toolz.curried import pipe, first, get -from pymks.fmks.data.elastic_fe import solve_fe +from pymks.fmks.data import solve_fe def test_3d(): diff --git a/pymks/fmks/tests/test_localization.py b/pymks/fmks/tests/test_localization.py index 4b1118a1..6ae12907 100644 --- a/pymks/fmks/tests/test_localization.py +++ b/pymks/fmks/tests/test_localization.py @@ -9,7 +9,7 @@ from pymks.fmks.bases.primitive import PrimitiveTransformer from pymks.fmks.localization import LocalizationRegressor from pymks.fmks.data.delta import generate_delta -from pymks.fmks.data.elastic_fe import solve_fe +from pymks.fmks.data import solve_fe def _get_x(): From 9a939f3d267e6058034fc8b3faec2119968e417d Mon Sep 17 00:00:00 2001 From: Daniel Wheeler Date: Wed, 17 Mar 2021 09:34:55 -0400 Subject: [PATCH 3/3] ci(circle): reduce circle ci load Remove elasticity.ipynb from circle tests as the load is often too much for Circle. --- .circleci/config.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 8cfcf8eb..cea338e3 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -39,7 +39,6 @@ jobs: source activate pymks python setup.py develop py.test pymks/fmks - py.test notebooks/elasticity.ipynb py.test notebooks/filter.ipynb py.test notebooks/intro.ipynb py.test notebooks/multiphase.ipynb