first documentation

Author: Dieb

docs/.DS_Store

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = MDTS
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

docs/Makefile

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+#
+# MDTS documentation build configuration file, created by
+# sphinx-quickstart on Tue Jan 23 16:40:36 2018.
+#
+# 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.
+
+# 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.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# 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.mathjax']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'MDTS'
+copyright = u'2018, Thaer Dieb'
+author = u'Thaer Dieb'
+
+# 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.
+version = u'0.1'
+# The full version, including alpha/beta/rc tags.
+release = u'0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- 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 = 'sphinx_rtd_theme'
+
+# 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 = {}
+
+# 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_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'MDTSdoc'
+
+
+# -- 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': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'MDTS.tex', u'MDTS Documentation',
+     u'Thaer Dieb', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'mdts', u'MDTS Documentation',
+     [author], 1)
+]
+
+
+# -- 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 = [
+    (master_doc, 'MDTS', u'MDTS Documentation',
+     author, 'MDTS', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+

docs/_static/.DS_Store

@@ -0,0 +1,24 @@
+.. MDTS documentation master file, created by
+   sphinx-quickstart on Tue Jan 23 16:40:36 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to MDTS's documentation!
+================================
+**MDTS: Materials Design by Tree Search** 
+
+Tsuda lab at the University of Tokyo
+
+.. image:: /_static/images/mdts.png
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   method
+   installation
+   versions
+   usage
+   papers
+

docs/_static/images/.DS_Store

@@ -0,0 +1,13 @@
+Installation
+============
+
+Required Packages
+	- python >= 2.7.x 
+	- numpy >=1.12.x
+	- COMBO https://github.com/tsudalab/combo (in case you want to use Bayesian rollout function)
+
+Setup
+	- Download or clone the github repository, e.g.git clone https://github.com/tsudalab/MDTS
+	- CD to the MDTS folder
+	- python setup.py install
+	- Please refer to test.py file for a use case

docs/_static/images/hybrid.png

@@ -0,0 +1,12 @@
+Method
+======
+
+Materials design process is often represented as a black-box function f(x) optimization problem.
+
+Monte Carlo tree search (MCTS) is an iterative, guided-random best-first search method that models the search space as a shallow tree. Each node of the tree represents an assignment of an atom of a certain type into a position in the structure. At the beginning, only the root node exists. Within a predetermined number of required experiments, the tree grows gradually in an iterative manner. Each iteration consists of 4 steps: Selection, Expansion, Simulation, and Backpropagation. In the Selection step, the tree is traversed from root to a leaf node following the child with the best score (children are scored using several methods, most commonly Upper Confidence Bound (UCB)). In Expansion step, children are generated under the selected node. The simulation step checks the merit of the new children by evaluating a full solution obtained at each child using experiment or simulation. Finally, the Backpropagation step updates the node information back to the root. A new iteration then begins.
+
+To obtain a full solution from a shallow tree, several strategies can be used. The most simple one is the random completion (filling the rest of the positions randomly), a cheap and less efficient solution.
+
+We use Bayesian learning to obtain full solution from a shallow tree. Bayesian optimization methods maintain a surrogate model of f(x), most commonly, Gaussian process (GP). A pool of candidate is generated where each data point represents a full structure. GP starts with an initial set of randomly selected data points from the pool. GP is updated as more data points are observed. An acquisition function is, then, used to determine where to query f(x) by quantifying how promising a data point is using both predicted value and prediction uncertainty. 
+
+.. image:: /_static/images/hybrid.png

docs/_static/images/mdts.png

@@ -0,0 +1,9 @@
+Publications
+============
+
+If you use this package, please cite us:
+	 Thaer M. Dieb, Shenghong Ju, Kazuki Yoshizoe, Zhufeng Hou, Junichiro Shiomi and Koji Tsuda. MDTS: Automatic Complex Materials Design using Monte Carlo Tree Search. Sci. Tech. Adv. Mater. 18, 498 (2017)
+
+Publications that have cited our work
+	- Xiufeng Yang, Jinzhe Zhang, Kazuki Yoshizoe, Kei Terayama, Koji Tsuda. ChemTS: an efficient python library for de novo molecular generation. Sci. Tech. Adv. Mater. 18:1, pages 972-976. (2017)
+	- Thaer M. Dieb, Koji Tsuda. Machine Learning-Based Experimental Design in Materials Science. Nanoinformatics, pages 65-74 (2018)

docs/conf.py

@@ -0,0 +1,104 @@
+Usage
+=====
+
+
+After installation:
+
+- import mdts package into your code ::
+
+	import mots
+
+- implement the get_reward (struct) function: This function evaluates the solution, that is the material structure, usually by a simulation function. It takes a python list representing the structure and returns the reward, usually the material property to be optimized. If no reward shall be return, use the **False** value as an output.
+- set the search tree object (mdts.Tree): This object will set the parameters for constructing the shallow tree. The parameters are as follows:
+
+	+ no_positions: number of positions in each structure to be set. For example, 16 positions.
+	+ atom_types: types of atoms. For example, 0 for Si and 1 for Ge
+	+ atom_const: number of each atom type in the structure. For example, 8 atoms Si and 8 atoms Ge. NONE indicates no constraints on number of that atom. Default is None
+	+ get_reward: the simulation function to evaluate a solution.
+	+ positions_order: define the order to assign atoms to the positions in the structure: "direct", "reverse","shuffle" or a list. Default is "reverse"
+	+ max_flag: if True the algorithm searches for maximum reward, else for minimum
+	+ expand_children : number of children to expand at each node. Default is "1". i.e. expand one child at a time.
+	+ play_out: number of playouts to be performed when creating a new node. Default is 1. Please note if you set the parameter use_combo to True, play_out can not be 1
+	+ play_out_selection: when performing multiple playouts, best or mean is returned. Default is best
+	+ space: numpy ndarray representing the candidates space if available or enumerable. If the space is not available or too expensive to enumerate, use NONE. Default is None. Note, if you specified the space, the "no_positions", "atom_types", and "atom_const" parameters will be ignored and there values will be taken from the ndarray of the space.
+	+ candidate_pool_size: the pool size that will be generated for the Bayesian rollout. It has to be set if you set use_combo=True, otherwise, it can be ignored.
+	+ ucb: it can be either "mean" or "best", it represents taking either average or best ucb score for Monte Carlo tree search. Default is "mean"
+	+ use_combo: weather to use Bayesian optimisation package (COMBO) or not in combination with Monte Carlo tree search to perform the rollout. If it is set to False, random rollout is performed.
+	+ combo_play_out: total number of candidates to be examined by COMBO while performing the rollout operation.
+	+ combo_init_random: the initial random selection for Bayesian optimisation. Default is 1
+	+ combo_step: the interval for Bayesian optimisation to perform hyper-parameter optimization. Default is 1
+::
+
+	myTree=mdts.Tree(no_positions=16, atom_types=[0,1], atom_const=[8,8], get_reward=get_reward, positions_order=range(16),
+                max_flag=True, expand_children=2, play_out=5, play_out_selection="best", space=None, candidate_pool_size=100,
+                 ucb="mean", use_combo=True, combo_play_out=20, combo_init_random=5, combo_step=5)
+- start the search by defining the required number of iterations. Search function will return an object of the class Result::
+
+	res=myTree.search(display=True,no_candidates=500)
+
+- search results can be obtained using the following properties of the class Result:
+
+	+ Optimal reward::
+
+		print res.optimal_fx
+
+	+ List of optimal candidates::
+
+		print res.optimal_candidate
+
+	+ List of tuples with the candidates examined and their rewards::
+
+		print res.checked_candidates_DS
+
+	+ Number of examined candidates::
+
+		print res.checked_candidates_size
+
+	+ List of chosen candidates in order::
+
+		print res.checked_candidates
+
+	+ List of simulated candidates rewards in order::
+
+		print res.fx
+
+	+ List of current best reward::
+
+		print res.best_fx
+
+	+ Maximum depth reached::
+
+		print res.max_depth_reached
+
+	+ Number of nodes constructed::
+
+		print res.no_nodes
+
+	+ Average visit per node::
+
+		print res.avg_node_visit
+
+- save and load results
+
+	+ Save results::
+
+		res.save('results.npz')
+
+	+Load results::
+
+		new_res=mdts.Result()
+		new_res.load('results.npz')
+		print new_res.optimal_fx
+
+
+- The tree can be saved::
+
+	mdts.save_tree(myTree,'Tree_file')
+	del myTree
+
+- Load the tree and continue the search from where you left it::
+
+	myNewTree = mdts.load_tree('Tree_file')
+	newTree_res=myNewTree.search(display=True, no_candidates=600)
+	print newTree_res.checked_candidates_size
+

docs/index.rst

@@ -0,0 +1,3 @@
+Versions
+========
+Current release version is 0.6