Remove document and demo in RABIT. (#9246)
This commit is contained in:
Jiaming Yuan
GitHub
parent
7f9cb921f4
commit
fc8110ef79
52
rabit/.gitignore
vendored
52
rabit/.gitignore
vendored
@ -1,52 +0,0 @@
|
||||
# Compiled Object files
|
||||
*.slo
|
||||
*.lo
|
||||
*.o
|
||||
*.obj
|
||||
|
||||
# Precompiled Headers
|
||||
*.gch
|
||||
*.pch
|
||||
*.lnk
|
||||
# Compiled Dynamic libraries
|
||||
*.so
|
||||
*.dylib
|
||||
*.dll
|
||||
|
||||
# Fortran module files
|
||||
*.mod
|
||||
|
||||
# Compiled Static libraries
|
||||
*.lai
|
||||
*.la
|
||||
*.a
|
||||
*.lib
|
||||
|
||||
# Executables
|
||||
*.miss
|
||||
*.exe
|
||||
*.out
|
||||
*.app
|
||||
*~
|
||||
*.pyc
|
||||
*.mpi
|
||||
*.exe
|
||||
*tmp*
|
||||
*.rabit
|
||||
*.mock
|
||||
recommonmark
|
||||
recom
|
||||
_*
|
||||
|
||||
#mpi lib
|
||||
mpich/
|
||||
mpich-3.2/
|
||||
|
||||
# Jetbrain
|
||||
.idea
|
||||
cmake-build-debug/
|
||||
.vscode/
|
||||
|
||||
# cmake
|
||||
build/
|
||||
compile_commands.json
|
||||
5
rabit/doc/.gitignore
vendored
5
rabit/doc/.gitignore
vendored
@ -1,5 +0,0 @@
|
||||
html
|
||||
latex
|
||||
*.sh
|
||||
_*
|
||||
doxygen
|
||||
@ -1,281 +0,0 @@
|
||||
# Doxyfile 1.7.6.1
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Project related configuration options
|
||||
#---------------------------------------------------------------------------
|
||||
DOXYFILE_ENCODING = UTF-8
|
||||
PROJECT_NAME = "rabit"
|
||||
PROJECT_NUMBER =
|
||||
PROJECT_BRIEF =
|
||||
PROJECT_LOGO =
|
||||
OUTPUT_DIRECTORY = ../doc/doxygen
|
||||
CREATE_SUBDIRS = NO
|
||||
OUTPUT_LANGUAGE = English
|
||||
BRIEF_MEMBER_DESC = YES
|
||||
REPEAT_BRIEF = YES
|
||||
ABBREVIATE_BRIEF =
|
||||
ALWAYS_DETAILED_SEC = NO
|
||||
INLINE_INHERITED_MEMB = NO
|
||||
FULL_PATH_NAMES = YES
|
||||
STRIP_FROM_PATH =
|
||||
STRIP_FROM_INC_PATH =
|
||||
SHORT_NAMES = NO
|
||||
JAVADOC_AUTOBRIEF = NO
|
||||
QT_AUTOBRIEF = NO
|
||||
MULTILINE_CPP_IS_BRIEF = NO
|
||||
INHERIT_DOCS = YES
|
||||
SEPARATE_MEMBER_PAGES = NO
|
||||
TAB_SIZE = 8
|
||||
ALIASES =
|
||||
TCL_SUBST =
|
||||
OPTIMIZE_OUTPUT_FOR_C = YES
|
||||
OPTIMIZE_OUTPUT_JAVA = NO
|
||||
OPTIMIZE_FOR_FORTRAN = NO
|
||||
OPTIMIZE_OUTPUT_VHDL = NO
|
||||
EXTENSION_MAPPING =
|
||||
BUILTIN_STL_SUPPORT = NO
|
||||
CPP_CLI_SUPPORT = NO
|
||||
SIP_SUPPORT = NO
|
||||
IDL_PROPERTY_SUPPORT = YES
|
||||
DISTRIBUTE_GROUP_DOC = NO
|
||||
SUBGROUPING = YES
|
||||
INLINE_GROUPED_CLASSES = NO
|
||||
INLINE_SIMPLE_STRUCTS = NO
|
||||
TYPEDEF_HIDES_STRUCT = NO
|
||||
LOOKUP_CACHE_SIZE = 0
|
||||
#---------------------------------------------------------------------------
|
||||
# Build related configuration options
|
||||
#---------------------------------------------------------------------------
|
||||
EXTRACT_ALL = NO
|
||||
EXTRACT_PRIVATE = NO
|
||||
EXTRACT_STATIC = NO
|
||||
EXTRACT_LOCAL_CLASSES = YES
|
||||
EXTRACT_LOCAL_METHODS = NO
|
||||
EXTRACT_ANON_NSPACES = NO
|
||||
HIDE_UNDOC_MEMBERS = NO
|
||||
HIDE_UNDOC_CLASSES = YES
|
||||
HIDE_FRIEND_COMPOUNDS = NO
|
||||
HIDE_IN_BODY_DOCS = NO
|
||||
INTERNAL_DOCS = NO
|
||||
CASE_SENSE_NAMES = YES
|
||||
HIDE_SCOPE_NAMES = NO
|
||||
SHOW_INCLUDE_FILES = YES
|
||||
FORCE_LOCAL_INCLUDES = NO
|
||||
INLINE_INFO = YES
|
||||
SORT_MEMBER_DOCS = YES
|
||||
SORT_BRIEF_DOCS = NO
|
||||
SORT_MEMBERS_CTORS_1ST = NO
|
||||
SORT_GROUP_NAMES = NO
|
||||
SORT_BY_SCOPE_NAME = NO
|
||||
STRICT_PROTO_MATCHING = NO
|
||||
GENERATE_TODOLIST = YES
|
||||
GENERATE_TESTLIST = YES
|
||||
GENERATE_BUGLIST = YES
|
||||
GENERATE_DEPRECATEDLIST= YES
|
||||
ENABLED_SECTIONS =
|
||||
MAX_INITIALIZER_LINES = 30
|
||||
SHOW_USED_FILES = YES
|
||||
SHOW_FILES = YES
|
||||
SHOW_NAMESPACES = YES
|
||||
FILE_VERSION_FILTER =
|
||||
LAYOUT_FILE =
|
||||
CITE_BIB_FILES =
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to warning and progress messages
|
||||
#---------------------------------------------------------------------------
|
||||
QUIET = NO
|
||||
WARNINGS = YES
|
||||
WARN_IF_UNDOCUMENTED = YES
|
||||
WARN_IF_DOC_ERROR = YES
|
||||
WARN_NO_PARAMDOC = YES
|
||||
WARN_FORMAT = "$file:$line: $text"
|
||||
WARN_LOGFILE =
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the input files
|
||||
#---------------------------------------------------------------------------
|
||||
INPUT = rabit
|
||||
INPUT_ENCODING = UTF-8
|
||||
FILE_PATTERNS =
|
||||
RECURSIVE = NO
|
||||
EXCLUDE =
|
||||
EXCLUDE_SYMLINKS = NO
|
||||
EXCLUDE_PATTERNS = *-inl.hpp
|
||||
EXCLUDE_SYMBOLS =
|
||||
EXAMPLE_PATH =
|
||||
EXAMPLE_PATTERNS =
|
||||
EXAMPLE_RECURSIVE = NO
|
||||
IMAGE_PATH =
|
||||
INPUT_FILTER =
|
||||
FILTER_PATTERNS =
|
||||
FILTER_SOURCE_FILES = NO
|
||||
FILTER_SOURCE_PATTERNS =
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to source browsing
|
||||
#---------------------------------------------------------------------------
|
||||
SOURCE_BROWSER = NO
|
||||
INLINE_SOURCES = NO
|
||||
STRIP_CODE_COMMENTS = YES
|
||||
REFERENCED_BY_RELATION = NO
|
||||
REFERENCES_RELATION = NO
|
||||
REFERENCES_LINK_SOURCE = YES
|
||||
USE_HTAGS = NO
|
||||
VERBATIM_HEADERS = YES
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the alphabetical class index
|
||||
#---------------------------------------------------------------------------
|
||||
ALPHABETICAL_INDEX = YES
|
||||
COLS_IN_ALPHA_INDEX = 5
|
||||
IGNORE_PREFIX =
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the HTML output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_HTML = YES
|
||||
HTML_OUTPUT = html
|
||||
HTML_FILE_EXTENSION = .html
|
||||
HTML_HEADER =
|
||||
HTML_FOOTER =
|
||||
HTML_STYLESHEET =
|
||||
HTML_EXTRA_FILES =
|
||||
HTML_COLORSTYLE_HUE = 220
|
||||
HTML_COLORSTYLE_SAT = 100
|
||||
HTML_COLORSTYLE_GAMMA = 80
|
||||
HTML_TIMESTAMP = YES
|
||||
HTML_DYNAMIC_SECTIONS = NO
|
||||
GENERATE_DOCSET = NO
|
||||
DOCSET_FEEDNAME = "Doxygen generated docs"
|
||||
DOCSET_BUNDLE_ID = org.doxygen.Project
|
||||
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
|
||||
DOCSET_PUBLISHER_NAME = Publisher
|
||||
GENERATE_HTMLHELP = NO
|
||||
CHM_FILE =
|
||||
HHC_LOCATION =
|
||||
GENERATE_CHI = NO
|
||||
CHM_INDEX_ENCODING =
|
||||
BINARY_TOC = NO
|
||||
TOC_EXPAND = NO
|
||||
GENERATE_QHP = NO
|
||||
QCH_FILE =
|
||||
QHP_NAMESPACE = org.doxygen.Project
|
||||
QHP_VIRTUAL_FOLDER = doc
|
||||
QHP_CUST_FILTER_NAME =
|
||||
QHP_CUST_FILTER_ATTRS =
|
||||
QHP_SECT_FILTER_ATTRS =
|
||||
QHG_LOCATION =
|
||||
GENERATE_ECLIPSEHELP = NO
|
||||
ECLIPSE_DOC_ID = org.doxygen.Project
|
||||
DISABLE_INDEX = NO
|
||||
GENERATE_TREEVIEW = NO
|
||||
ENUM_VALUES_PER_LINE = 4
|
||||
TREEVIEW_WIDTH = 250
|
||||
EXT_LINKS_IN_WINDOW = NO
|
||||
FORMULA_FONTSIZE = 10
|
||||
FORMULA_TRANSPARENT = YES
|
||||
USE_MATHJAX = NO
|
||||
MATHJAX_RELPATH = http://www.mathjax.org/mathjax
|
||||
MATHJAX_EXTENSIONS =
|
||||
SEARCHENGINE = YES
|
||||
SERVER_BASED_SEARCH = NO
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the LaTeX output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_LATEX = YES
|
||||
LATEX_OUTPUT = latex
|
||||
LATEX_CMD_NAME = latex
|
||||
MAKEINDEX_CMD_NAME = makeindex
|
||||
COMPACT_LATEX = NO
|
||||
PAPER_TYPE = a4
|
||||
EXTRA_PACKAGES =
|
||||
LATEX_HEADER =
|
||||
LATEX_FOOTER =
|
||||
PDF_HYPERLINKS = YES
|
||||
USE_PDFLATEX = YES
|
||||
LATEX_BATCHMODE = NO
|
||||
LATEX_HIDE_INDICES = NO
|
||||
LATEX_SOURCE_CODE = NO
|
||||
LATEX_BIB_STYLE = plain
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the RTF output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_RTF = NO
|
||||
RTF_OUTPUT = rtf
|
||||
COMPACT_RTF = NO
|
||||
RTF_HYPERLINKS = NO
|
||||
RTF_STYLESHEET_FILE =
|
||||
RTF_EXTENSIONS_FILE =
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the man page output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_MAN = NO
|
||||
MAN_OUTPUT = man
|
||||
MAN_EXTENSION = .3
|
||||
MAN_LINKS = NO
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the XML output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_XML = YES
|
||||
XML_OUTPUT = xml
|
||||
XML_PROGRAMLISTING = YES
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options for the AutoGen Definitions output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_AUTOGEN_DEF = NO
|
||||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the Perl module output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_PERLMOD = NO
|
||||
PERLMOD_LATEX = NO
|
||||
PERLMOD_PRETTY = YES
|
||||
PERLMOD_MAKEVAR_PREFIX =
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the preprocessor
|
||||
#---------------------------------------------------------------------------
|
||||
ENABLE_PREPROCESSING = NO
|
||||
MACRO_EXPANSION = NO
|
||||
EXPAND_ONLY_PREDEF = NO
|
||||
SEARCH_INCLUDES = YES
|
||||
INCLUDE_PATH =
|
||||
INCLUDE_FILE_PATTERNS =
|
||||
PREDEFINED =
|
||||
EXPAND_AS_DEFINED =
|
||||
SKIP_FUNCTION_MACROS = YES
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration::additions related to external references
|
||||
#---------------------------------------------------------------------------
|
||||
TAGFILES =
|
||||
GENERATE_TAGFILE =
|
||||
ALLEXTERNALS = NO
|
||||
EXTERNAL_GROUPS = YES
|
||||
PERL_PATH = /usr/bin/perl
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the dot tool
|
||||
#---------------------------------------------------------------------------
|
||||
CLASS_DIAGRAMS = YES
|
||||
MSCGEN_PATH =
|
||||
HIDE_UNDOC_RELATIONS = YES
|
||||
HAVE_DOT = NO
|
||||
DOT_NUM_THREADS = 0
|
||||
DOT_FONTNAME = Helvetica
|
||||
DOT_FONTSIZE = 10
|
||||
DOT_FONTPATH =
|
||||
CLASS_GRAPH = YES
|
||||
COLLABORATION_GRAPH = YES
|
||||
GROUP_GRAPHS = YES
|
||||
UML_LOOK = NO
|
||||
TEMPLATE_RELATIONS = NO
|
||||
INCLUDE_GRAPH = YES
|
||||
INCLUDED_BY_GRAPH = YES
|
||||
CALL_GRAPH = NO
|
||||
CALLER_GRAPH = NO
|
||||
GRAPHICAL_HIERARCHY = YES
|
||||
DIRECTORY_GRAPH = YES
|
||||
DOT_IMAGE_FORMAT = png
|
||||
INTERACTIVE_SVG = NO
|
||||
DOT_PATH =
|
||||
DOTFILE_DIRS =
|
||||
MSCFILE_DIRS =
|
||||
DOT_GRAPH_MAX_NODES = 50
|
||||
MAX_DOT_GRAPH_DEPTH = 0
|
||||
DOT_TRANSPARENT = NO
|
||||
DOT_MULTI_TARGETS = YES
|
||||
GENERATE_LEGEND = YES
|
||||
DOT_CLEANUP = YES
|
||||
@ -1,192 +0,0 @@
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
|
||||
# User-friendly check for sphinx-build
|
||||
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
|
||||
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
|
||||
endif
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
|
||||
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " dirhtml to make HTML files named index.html in directories"
|
||||
@echo " singlehtml to make a single large HTML file"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " qthelp to make HTML files and a qthelp project"
|
||||
@echo " applehelp to make an Apple Help Book"
|
||||
@echo " devhelp to make HTML files and a Devhelp project"
|
||||
@echo " epub to make an epub"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " texinfo to make Texinfo files"
|
||||
@echo " info to make Texinfo files and run them through makeinfo"
|
||||
@echo " gettext to make PO message catalogs"
|
||||
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||
@echo " xml to make Docutils-native XML files"
|
||||
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||
@echo " coverage to run coverage check of the documentation (if enabled)"
|
||||
|
||||
clean:
|
||||
rm -rf $(BUILDDIR)/*
|
||||
|
||||
html:
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
dirhtml:
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||
|
||||
singlehtml:
|
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||
|
||||
pickle:
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
json:
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
htmlhelp:
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||
|
||||
qthelp:
|
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/rabit.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/rabit.qhc"
|
||||
|
||||
applehelp:
|
||||
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
|
||||
@echo
|
||||
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
|
||||
@echo "N.B. You won't be able to view it unless you put it in" \
|
||||
"~/Library/Documentation/Help or install it in your application" \
|
||||
"bundle."
|
||||
|
||||
devhelp:
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/rabit"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/rabit"
|
||||
@echo "# devhelp"
|
||||
|
||||
epub:
|
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
latex:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)."
|
||||
|
||||
latexpdf:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
latexpdfja:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through platex and dvipdfmx..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
text:
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||
|
||||
man:
|
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||
@echo
|
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||
|
||||
texinfo:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo
|
||||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
|
||||
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||
"(use \`make info' here to do that automatically)."
|
||||
|
||||
info:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo "Running Texinfo files through makeinfo..."
|
||||
make -C $(BUILDDIR)/texinfo info
|
||||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
|
||||
|
||||
gettext:
|
||||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
|
||||
@echo
|
||||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
|
||||
|
||||
changes:
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||
|
||||
linkcheck:
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
doctest:
|
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt."
|
||||
|
||||
coverage:
|
||||
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
|
||||
@echo "Testing of coverage in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/coverage/python.txt."
|
||||
|
||||
xml:
|
||||
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
|
||||
@echo
|
||||
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
|
||||
|
||||
pseudoxml:
|
||||
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
|
||||
@echo
|
||||
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
|
||||
@ -1,184 +0,0 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# documentation build configuration file, created by
|
||||
# sphinx-quickstart on Thu Jul 23 19:40:08 2015.
|
||||
#
|
||||
# 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, subprocess
|
||||
import shlex
|
||||
# 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.
|
||||
curr_path = os.path.dirname(os.path.abspath(os.path.expanduser(__file__)))
|
||||
libpath = os.path.join(curr_path, '../wrapper/')
|
||||
sys.path.insert(0, os.path.join(curr_path, '../wrapper/'))
|
||||
sys.path.insert(0, curr_path)
|
||||
from sphinx_util import MarkdownParser, AutoStructify
|
||||
|
||||
# -- General configuration ------------------------------------------------
|
||||
|
||||
# General information about the project.
|
||||
project = u'rabit'
|
||||
copyright = u'2015, rabit developers'
|
||||
author = u'rabit developers'
|
||||
github_doc_root = 'https://github.com/dmlc/rabit/tree/master/doc/'
|
||||
|
||||
# add markdown parser
|
||||
MarkdownParser.github_doc_root = github_doc_root
|
||||
source_parsers = {
|
||||
'.md': MarkdownParser,
|
||||
}
|
||||
# Version information.
|
||||
import rabit
|
||||
|
||||
version = rabit.__version__
|
||||
release = rabit.__version__
|
||||
|
||||
# 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.napoleon',
|
||||
'sphinx.ext.mathjax',
|
||||
'breathe',
|
||||
]
|
||||
|
||||
# Use breathe to include doxygen documents
|
||||
breathe_projects = {'rabit' : 'doxygen/xml/'}
|
||||
breathe_default_project = 'rabit'
|
||||
|
||||
# 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', '.md']
|
||||
|
||||
# The encoding of source files.
|
||||
#source_encoding = 'utf-8-sig'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# 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
|
||||
|
||||
# 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']
|
||||
|
||||
# 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 = []
|
||||
|
||||
# If true, keep warnings as "system message" paragraphs in the built documents.
|
||||
#keep_warnings = False
|
||||
|
||||
# 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 = 'alabaster'
|
||||
|
||||
# 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']
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = project + 'doc'
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
latex_elements = {
|
||||
}
|
||||
|
||||
# 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, 'rabit.tex', project,
|
||||
author, 'manual'),
|
||||
]
|
||||
|
||||
# hook for doxygen
|
||||
def run_doxygen(folder):
|
||||
"""Run the doxygen make command in the designated folder."""
|
||||
try:
|
||||
retcode = subprocess.call("cd %s; make doxygen" % folder, shell=True)
|
||||
if retcode < 0:
|
||||
sys.stderr.write("doxygen terminated by signal %s" % (-retcode))
|
||||
except OSError as e:
|
||||
sys.stderr.write("doxygen execution failed: %s" % e)
|
||||
|
||||
|
||||
def run_build_lib(folder):
|
||||
"""Run the doxygen make command in the designated folder."""
|
||||
try:
|
||||
retcode = subprocess.call("cd %s; make" % folder, shell=True)
|
||||
retcode = subprocess.call("rm -rf _build/html/doxygen", shell=True)
|
||||
retcode = subprocess.call("mkdir _build", shell=True)
|
||||
retcode = subprocess.call("mkdir _build/html", shell=True)
|
||||
retcode = subprocess.call("cp -rf doxygen/html _build/html/doxygen", shell=True)
|
||||
if retcode < 0:
|
||||
sys.stderr.write("build terminated by signal %s" % (-retcode))
|
||||
except OSError as e:
|
||||
sys.stderr.write("build execution failed: %s" % e)
|
||||
|
||||
|
||||
def generate_doxygen_xml(app):
|
||||
"""Run the doxygen make commands if we're on the ReadTheDocs server"""
|
||||
read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
|
||||
if read_the_docs_build:
|
||||
run_doxygen('..')
|
||||
sys.stderr.write('Check if shared lib exists\n')
|
||||
run_build_lib('..')
|
||||
sys.stderr.write('The wrapper path: %s\n' % str(os.listdir('../wrapper')))
|
||||
rabit._loadlib()
|
||||
|
||||
|
||||
def setup(app):
|
||||
# Add hook for building doxygen xml when needed
|
||||
app.connect("builder-inited", generate_doxygen_xml)
|
||||
app.add_config_value('recommonmark_config', {
|
||||
'url_resolver': lambda url: github_doc_root + url,
|
||||
}, True)
|
||||
app.add_transform(AutoStructify)
|
||||
@ -1,9 +0,0 @@
|
||||
C++ Library API of Rabit
|
||||
========================
|
||||
This page contains document of Library API of rabit.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
|
||||
.. doxygennamespace:: rabit
|
||||
```
|
||||
@ -1,383 +0,0 @@
|
||||
Tutorial
|
||||
========
|
||||
This is rabit's tutorial, a ***Reliable Allreduce and Broadcast Interface***.
|
||||
All the example codes are in the [guide](https://github.com/dmlc/rabit/blob/master/guide/) folder of the project.
|
||||
To run the examples locally, you will need to build them with ```make```.
|
||||
|
||||
**List of Topics**
|
||||
* [What is Allreduce](#what-is-allreduce)
|
||||
* [Common Use Case](#common-use-case)
|
||||
* [Use Rabit API](#use-rabit-api)
|
||||
- [Structure of a Rabit Program](#structure-of-a-rabit-program)
|
||||
- [Allreduce and Lazy Preparation](#allreduce-and-lazy-preparation)
|
||||
- [Checkpoint and LazyCheckpoint](#checkpoint-and-lazycheckpoint)
|
||||
* [Compile Programs with Rabit](#compile-programs-with-rabit)
|
||||
* [Running Rabit Jobs](#running-rabit-jobs)
|
||||
* [Fault Tolerance](#fault-tolerance)
|
||||
|
||||
What is Allreduce
|
||||
-----------------
|
||||
The main methods provided by rabit are Allreduce and Broadcast. Allreduce performs reduction across different computation nodes,
|
||||
and returns the result to every node. To understand the behavior of the function, consider the following example in [basic.cc](../guide/basic.cc) (there is a python example right after this if you are more familiar with python).
|
||||
```c++
|
||||
#include <rabit.h>
|
||||
using namespace rabit;
|
||||
const int N = 3;
|
||||
int main(int argc, char *argv[]) {
|
||||
int a[N];
|
||||
rabit::Init(argc, argv);
|
||||
for (int i = 0; i < N; ++i) {
|
||||
a[i] = rabit::GetRank() + i;
|
||||
}
|
||||
printf("@node[%d] before-allreduce: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
// allreduce take max of each elements in all processes
|
||||
Allreduce<op::Max>(&a[0], N);
|
||||
printf("@node[%d] after-allreduce-max: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
// second allreduce that sums everything up
|
||||
Allreduce<op::Sum>(&a[0], N);
|
||||
printf("@node[%d] after-allreduce-sum: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
rabit::Finalize();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
You can run the example using the rabit_demo.py script. The following command
|
||||
starts the rabit program with two worker processes.
|
||||
```bash
|
||||
../tracker/rabit_demo.py -n 2 basic.rabit
|
||||
```
|
||||
This will start two processes, one process with rank 0 and the other with rank 1, both processes run the same code.
|
||||
The ```rabit::GetRank()``` function returns the rank of current process.
|
||||
|
||||
Before the call to Allreduce, process 0 contains the array ```a = {0, 1, 2}```, while process 1 has the array
|
||||
```a = {1, 2, 3}```. After the call to Allreduce, the array contents in all processes are replaced by the
|
||||
reduction result (in this case, the maximum value in each position across all the processes). So, after the
|
||||
Allreduce call, the result will become ```a = {1, 2, 3}```.
|
||||
Rabit provides different reduction operators, for example, if you change ```op::Max``` to ```op::Sum```,
|
||||
the reduction operation will be a summation, and the result will become ```a = {1, 3, 5}```.
|
||||
You can also run the example with different processes by setting -n to different values.
|
||||
|
||||
If you are more familiar with python, you can also use rabit in python. The same example as before can be found in [basic.py](../guide/basic.py):
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import rabit
|
||||
|
||||
rabit.init()
|
||||
n = 3
|
||||
rank = rabit.get_rank()
|
||||
a = np.zeros(n)
|
||||
for i in xrange(n):
|
||||
a[i] = rank + i
|
||||
|
||||
print '@node[%d] before-allreduce: a=%s' % (rank, str(a))
|
||||
a = rabit.allreduce(a, rabit.MAX)
|
||||
print '@node[%d] after-allreduce-max: a=%s' % (rank, str(a))
|
||||
a = rabit.allreduce(a, rabit.SUM)
|
||||
print '@node[%d] after-allreduce-sum: a=%s' % (rank, str(a))
|
||||
rabit.finalize()
|
||||
```
|
||||
You can run the program using the following command
|
||||
```bash
|
||||
../tracker/rabit_demo.py -n 2 basic.py
|
||||
```
|
||||
|
||||
Broadcast is another method provided by rabit besides Allreduce. This function allows one node to broadcast its
|
||||
local data to all other nodes. The following code in [broadcast.cc](../guide/broadcast.cc) broadcasts a string from
|
||||
node 0 to all other nodes.
|
||||
```c++
|
||||
#include <rabit.h>
|
||||
using namespace rabit;
|
||||
const int N = 3;
|
||||
int main(int argc, char *argv[]) {
|
||||
rabit::Init(argc, argv);
|
||||
std::string s;
|
||||
if (rabit::GetRank() == 0) s = "hello world";
|
||||
printf("@node[%d] before-broadcast: s=\"%s\"\n",
|
||||
rabit::GetRank(), s.c_str());
|
||||
// broadcast s from node 0 to all other nodes
|
||||
rabit::Broadcast(&s, 0);
|
||||
printf("@node[%d] after-broadcast: s=\"%s\"\n",
|
||||
rabit::GetRank(), s.c_str());
|
||||
rabit::Finalize();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
The following command starts the program with three worker processes.
|
||||
```bash
|
||||
../tracker/rabit_demo.py -n 3 broadcast.rabit
|
||||
```
|
||||
Besides strings, rabit also allows to broadcast constant size array and vectors.
|
||||
|
||||
The counterpart in python can be found in [broadcast.py](../guide/broadcast.py). Here is a snippet so that you can get a better sense of how simple is to use the python library:
|
||||
|
||||
```python
|
||||
import rabit
|
||||
rabit.init()
|
||||
n = 3
|
||||
rank = rabit.get_rank()
|
||||
s = None
|
||||
if rank == 0:
|
||||
s = {'hello world':100, 2:3}
|
||||
print '@node[%d] before-broadcast: s=\"%s\"' % (rank, str(s))
|
||||
s = rabit.broadcast(s, 0)
|
||||
print '@node[%d] after-broadcast: s=\"%s\"' % (rank, str(s))
|
||||
rabit.finalize()
|
||||
```
|
||||
|
||||
Common Use Case
|
||||
---------------
|
||||
Many distributed machine learning algorithms involve splitting the data into different nodes,
|
||||
computing statistics locally, and finally aggregating them. Such workflow is usually done repetitively through many iterations before the algorithm converges. Allreduce naturally meets the structure of such programs,
|
||||
common use cases include:
|
||||
|
||||
* Aggregation of gradient values, which can be used in optimization methods such as L-BFGS.
|
||||
* Aggregation of other statistics, which can be used in KMeans and Gaussian Mixture Models.
|
||||
* Find the best split candidate and aggregation of split statistics, used for tree based models.
|
||||
|
||||
Rabit is a reliable and portable library for distributed machine learning programs, that allow programs to run reliably on different platforms.
|
||||
|
||||
Use Rabit API
|
||||
-------------
|
||||
This section introduces topics about how to use rabit API.
|
||||
You can always refer to [API Documentation](http://homes.cs.washington.edu/~tqchen/rabit/doc) for definition of each functions.
|
||||
This section trys to gives examples of different aspectes of rabit API.
|
||||
|
||||
#### Structure of a Rabit Program
|
||||
The following code illustrates the common structure of a rabit program. This is an abstract example,
|
||||
you can also refer to [wormhole](https://github.com/dmlc/wormhole/blob/master/learn/kmeans/kmeans.cc) for an example implementation of kmeans algorithm.
|
||||
|
||||
```c++
|
||||
#include <rabit.h>
|
||||
int main(int argc, char *argv[]) {
|
||||
...
|
||||
rabit::Init(argc, argv);
|
||||
// sync on expected model size before load checkpoint, if we pass rabit_bootstrap_cache=true
|
||||
rabit::Allreduce<rabit::op::Max>(&model.size(), 1);
|
||||
// load the latest checked model
|
||||
int version = rabit::LoadCheckPoint(&model);
|
||||
// initialize the model if it is the first version
|
||||
if (version == 0) model.InitModel();
|
||||
// the version number marks the iteration to resume
|
||||
for (int iter = version; iter < max_iter; ++iter) {
|
||||
// at this point, the model object should allow us to recover the program state
|
||||
...
|
||||
// each iteration can contain multiple calls of allreduce/broadcast
|
||||
rabit::Allreduce<rabit::op::Max>(&data[0], n);
|
||||
...
|
||||
// checkpoint model after one iteration finishes
|
||||
rabit::CheckPoint(&model);
|
||||
}
|
||||
rabit::Finalize();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
|
||||
Besides the common Allreduce and Broadcast functions, there are two additional functions: ```LoadCheckPoint```
|
||||
and ```CheckPoint```. These two functions are used for fault-tolerance purposes.
|
||||
As mentioned before, traditional machine learning programs involve several iterations. In each iteration, we start with a model, make some calls
|
||||
to Allreduce or Broadcast and update the model. The calling sequence in each iteration does not need to be the same.
|
||||
|
||||
* When the nodes start from the beginning (i.e. iteration 0), ```LoadCheckPoint``` returns 0, so we can initialize the model.
|
||||
* ```CheckPoint``` saves the model after each iteration.
|
||||
- Efficiency Note: the model is only kept in local memory and no save to disk is performed when calling Checkpoint
|
||||
* When a node goes down and restarts, ```LoadCheckPoint``` will recover the latest saved model, and
|
||||
* When a node goes down, the rest of the nodes will block in the call of Allreduce/Broadcast and wait for
|
||||
the recovery of the failed node until it catches up.
|
||||
|
||||
Please see the [Fault Tolerance](#fault-tolerance) section to understand the recovery procedure executed by rabit.
|
||||
|
||||
#### Allreduce and Lazy Preparation
|
||||
Allreduce is one of the most important function provided by rabit. You can call allreduce by specifying the
|
||||
reduction operator, pointer to the data and size of the buffer, as follows
|
||||
```c++
|
||||
Allreduce<operator>(pointer_of_data, size_of_data);
|
||||
```
|
||||
This is the basic use case of Allreduce function. It is common that user writes the code to prepare the data needed
|
||||
into the data buffer, pass the data to Allreduce function, and get the reduced result. However, when a node restarts
|
||||
from failure, we can directly recover the result from other nodes(see also [Fault Tolerance](#fault-tolerance)) and
|
||||
the data preparation procedure no longer necessary. Rabit Allreduce add an optional parameter preparation function
|
||||
to support such scenario. User can pass in a function that corresponds to the data preparation procedure to Allreduce
|
||||
calls, and the data preparation function will only be called when necessary. We use [lazy_allreduce.cc](../guide/lazy_allreduce.cc)
|
||||
as an example to demonstrate this feature. It is modified from [basic.cc](../guide/basic.cc), and you can compare the two codes.
|
||||
```c++
|
||||
#include <rabit.h>
|
||||
using namespace rabit;
|
||||
const int N = 3;
|
||||
int main(int argc, char *argv[]) {
|
||||
int a[N] = {0};
|
||||
rabit::Init(argc, argv);
|
||||
// lazy preparation function
|
||||
auto prepare = [&]() {
|
||||
printf("@node[%d] run prepare function\n", rabit::GetRank());
|
||||
for (int i = 0; i < N; ++i) {
|
||||
a[i] = rabit::GetRank() + i;
|
||||
}
|
||||
};
|
||||
printf("@node[%d] before-allreduce: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
// allreduce take max of each elements in all processes
|
||||
Allreduce<op::Max>(&a[0], N, prepare);
|
||||
printf("@node[%d] after-allreduce-sum: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
// rum second allreduce
|
||||
Allreduce<op::Sum>(&a[0], N);
|
||||
printf("@node[%d] after-allreduce-max: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
rabit::Finalize();
|
||||
return 0;
|
||||
}
|
||||
```
|
||||
Here we use features of C++11 because the lambda function makes things much shorter.
|
||||
There is also C++ compatible callback interface provided in the [API](http://homes.cs.washington.edu/~tqchen/rabit/doc).
|
||||
You can compile the program by typing ```make lazy_allreduce.mock```. We link against the mock library so that we can see
|
||||
the effect when a process goes down. You can run the program using the following command
|
||||
```bash
|
||||
../tracker/rabit_demo.py -n 2 lazy_allreduce.mock mock=0,0,1,0
|
||||
```
|
||||
The additional arguments ```mock=0,0,1,0``` will cause node 0 to kill itself before second call of Allreduce (see also [mock test](#link-against-mock-test-rabit-library)).
|
||||
You will find that the prepare function's print is only executed once and node 0 will no longer execute the preparation function when it restarts from failure.
|
||||
|
||||
You can also find python version of the example in [lazy_allreduce.py](../guide/lazy_allreduce.py), and run it using the followin command
|
||||
```bash
|
||||
../tracker/rabit_demo.py -n 2 lazy_allreduce.py mock=0,0,1,0
|
||||
|
||||
```
|
||||
|
||||
Since lazy preparation function may not be called during execution. User should be careful when using this feature. For example, a possible mistake
|
||||
could be putting some memory allocation code in the lazy preparation function, and the computing memory was not allocated when lazy preparation function is not called.
|
||||
The example in [lazy_allreduce.cc](../guide/lazy_allreduce.cc) provides a simple way to migrate normal prepration code([basic.cc](../guide/basic.cc)) to lazy version: wrap the preparation
|
||||
code with a lambda function, and pass it to allreduce.
|
||||
|
||||
#### Checkpoint and LazyCheckpoint
|
||||
Common machine learning algorithms usually involves iterative computation. As mentioned in the section ([Structure of a Rabit Program](#structure-of-a-rabit-program)),
|
||||
user can and should use Checkpoint to ```save``` the progress so far, so that when a node fails, the latest checkpointed model can be loaded.
|
||||
|
||||
There are two model arguments you can pass to Checkpoint and LoadCheckpoint: ```global_model``` and ```local_model```:
|
||||
* ```global_model``` refers to the model that is commonly shared across all the nodes
|
||||
- For example, the centriods of clusters in kmeans is shared across all nodes
|
||||
* ```local_model``` refers to the model that is specifically tied to the current node
|
||||
- For example, in topic modeling, the topic assignments of subset of documents in current node is local model
|
||||
|
||||
Because the different nature of the two types of models, different strategy will be used for them.
|
||||
```global_model``` is simply saved in local memory of each node, while ```local_model``` will replicated to some other
|
||||
nodes (selected using a ring replication strategy). The checkpoint is only saved in the memory without touching the disk which makes rabit programs more efficient.
|
||||
User is encouraged to use ```global_model``` only when is sufficient for better efficiency.
|
||||
|
||||
To enable a model class to be checked pointed, user can implement a [serialization interface](../include/rabit_serialization.h). The serialization interface already
|
||||
provide serialization functions of STL vector and string. For python API, user can checkpoint any python object that can be pickled.
|
||||
|
||||
There is a special Checkpoint function called [LazyCheckpoint](http://homes.cs.washington.edu/~tqchen/rabit/doc/namespacerabit.html#a99f74c357afa5fba2c80cc0363e4e459),
|
||||
which can be used for ```global_model``` only cases under certain condition.
|
||||
When LazyCheckpoint is called, no action is taken and the rabit engine only remembers the pointer to the model.
|
||||
The serialization will only happen when another node fails and the recovery starts. So user basically pays no extra cost calling LazyCheckpoint.
|
||||
To use this function, the user need to ensure the model remain unchanged until the last call of Allreduce/Broadcast in the current version finishes.
|
||||
So that when recovery procedure happens in these function calls, the serialized model will be the same.
|
||||
|
||||
For example, consider the following calling sequence
|
||||
```
|
||||
LazyCheckPoint, code1, Allreduce, code2, Broadcast, code3, LazyCheckPoint
|
||||
```
|
||||
The user must only change the model in code3. Such condition can usually be satiesfied in many scenarios, and user can use LazyCheckpoint to further
|
||||
improve the efficiency of the program.
|
||||
|
||||
|
||||
Compile Programs with Rabit
|
||||
---------------------------
|
||||
Rabit is a portable library, to use it, you only need to include the rabit header file.
|
||||
* You will need to add the path to [../include](../include) to the header search path of the compiler
|
||||
- Solution 1: add ```-I/path/to/rabit/include``` to the compiler flag in gcc or clang
|
||||
- Solution 2: add the path to the environment variable CPLUS_INCLUDE_PATH
|
||||
* You will need to add the path to [../lib](../lib) to the library search path of the compiler
|
||||
- Solution 1: add ```-L/path/to/rabit/lib``` to the linker flag
|
||||
- Solution 2: add the path to environment variable LIBRARY_PATH AND LD_LIBRARY_PATH
|
||||
* Link against lib/rabit.a
|
||||
- Add ```-lrabit``` to the linker flag
|
||||
|
||||
The procedure above allows you to compile a program with rabit. The following two sections contain additional
|
||||
options you can use to link against different backends other than the normal one.
|
||||
|
||||
#### Link against MPI Allreduce
|
||||
You can link against ```rabit_mpi.a``` instead of using MPI Allreduce, however, the resulting program is backed by MPI and
|
||||
is not fault tolerant anymore.
|
||||
* Simply change the linker flag from ```-lrabit``` to ```-lrabit_mpi```
|
||||
* The final linking needs to be done by mpi wrapper compiler ```mpicxx```
|
||||
|
||||
#### Link against Mock Test Rabit Library
|
||||
If you want to use a mock to test the program in order to see the behavior of the code when some nodes go down, you can link against ```rabit_mock.a``` .
|
||||
* Simply change the linker flag from ```-lrabit``` to ```-lrabit_mock```
|
||||
|
||||
The resulting rabit mock program can take in additional arguments in the following format
|
||||
```
|
||||
mock=rank,version,seq,ndeath
|
||||
```
|
||||
|
||||
The four integers specify an event that will cause the program to ```commit suicide```(exit with -2)
|
||||
* rank specifies the rank of the node to kill
|
||||
* version specifies the version (iteration) of the model where you want the process to die
|
||||
* seq specifies the sequence number of the Allreduce/Broadcast call since last checkpoint, where the process will be killed
|
||||
* ndeath specifies how many times this node died already
|
||||
|
||||
For example, consider the following script in the test case
|
||||
```bash
|
||||
../tracker/rabit_demo.py -n 10 test_model_recover 10000\
|
||||
mock=0,0,1,0 mock=1,1,1,0 mock=1,1,1,1
|
||||
```
|
||||
* The first mock will cause node 0 to exit when calling the second Allreduce/Broadcast (seq = 1) in iteration 0
|
||||
* The second mock will cause node 1 to exit when calling the second Allreduce/Broadcast (seq = 1) in iteration 1
|
||||
* The third mock will cause node 1 to exit again when calling second Allreduce/Broadcast (seq = 1) in iteration 1
|
||||
- Note that ndeath = 1 means this will happen only if node 1 died once, which is our case
|
||||
|
||||
Running Rabit Jobs
|
||||
------------------
|
||||
Rabit is a portable library that can run on multiple platforms.
|
||||
All the rabit jobs can be submitted using [dmlc-tracker](https://github.com/dmlc/dmlc-core/tree/master/tracker)
|
||||
|
||||
Fault Tolerance
|
||||
---------------
|
||||
This section introduces how fault tolerance works in rabit.
|
||||
The following figure shows how rabit deals with failures.
|
||||
|
||||
|
||||
|
||||
The scenario is as follows:
|
||||
* Node 1 fails between the first and second call of Allreduce after the second checkpoint
|
||||
* The other nodes wait in the call of the second Allreduce in order to help node 1 to recover.
|
||||
* When node 1 restarts, it will call ```LoadCheckPoint```, and get the latest checkpoint from one of the existing nodes.
|
||||
* Then node 1 can start from the latest checkpoint and continue running.
|
||||
* When node 1 calls the first Allreduce again, as the other nodes already know the result, node 1 can get it from one of them.
|
||||
* When node 1 reaches the second Allreduce, the other nodes find out that node 1 has catched up and they can continue the program normally.
|
||||
|
||||
This fault tolerance model is based on a key property of Allreduce and
|
||||
Broadcast: All the nodes get the same result after calling Allreduce/Broadcast.
|
||||
Because of this property, any node can record the results of history
|
||||
Allreduce/Broadcast calls. When a node is recovered, it can fetch the lost
|
||||
results from some alive nodes and rebuild its model.
|
||||
|
||||
The checkpoint is introduced so that we can discard the history results of
|
||||
Allreduce/Broadcast calls before the latest checkpoint. This saves memory
|
||||
consumption used for backup. The checkpoint of each node is a model defined by
|
||||
users and can be split into 2 parts: a global model and a local model. The
|
||||
global model is shared by all nodes and can be backed up by any nodes. The
|
||||
local model of a node is replicated to some other nodes (selected using a ring
|
||||
replication strategy). The checkpoint is only saved in the memory without
|
||||
touching the disk which makes rabit programs more efficient. The strategy of
|
||||
rabit is different from the fail-restart strategy where all the nodes restart
|
||||
from the same checkpoint when any of them fail. In rabit, all the alive nodes
|
||||
will block in the Allreduce call and help the recovery. To catch up, the
|
||||
recovered node fetches its latest checkpoint and the results of
|
||||
Allreduce/Broadcast calls after the checkpoint from some alive nodes.
|
||||
|
||||
This is just a conceptual introduction to rabit's fault tolerance model. The actual implementation is more sophisticated,
|
||||
and can deal with more complicated cases such as multiple nodes failure and node failure during recovery phase.
|
||||
|
||||
Rabit Timeout
|
||||
---------------
|
||||
|
||||
In certain cases, rabit cluster may suffer lack of resources to retry failed workers.
|
||||
Thanks to fault tolerant assumption with infinite retry, it might cause entire cluster hang infinitely.
|
||||
We introduce sidecar thread which runs when rabit fault tolerant runtime observed allreduce/broadcast errors.
|
||||
By default, it will wait for 30 mins before all workers program exit.
|
||||
User can opt-in this feature and change treshold by passing rabit_timeout=true and rabit_timeout_sec=x (in seconds).
|
||||
@ -1,24 +0,0 @@
|
||||
Rabit Documentation
|
||||
=====================
|
||||
rabit is a light weight library that provides a fault tolerant interface of Allreduce and Broadcast. It is designed to support easy implementations of distributed machine learning programs, many of which fall naturally under the Allreduce abstraction. The goal of rabit is to support **portable** , **scalable** and **reliable** distributed machine learning programs.
|
||||
|
||||
API Documents
|
||||
-------------
|
||||
```eval_rst
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
python_api.md
|
||||
cpp_api.md
|
||||
parameters.md
|
||||
guide.md
|
||||
```
|
||||
Indices and tables
|
||||
------------------
|
||||
|
||||
```eval_rst
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
```
|
||||
@ -1,21 +0,0 @@
|
||||
Parameters
|
||||
==========
|
||||
This section list all the parameters that can be passed to rabit::Init function as argv.
|
||||
All the parameters are passed in as string in format of ``parameter-name=parameter-value``.
|
||||
In most setting these parameters have default value or will be automatically detected,
|
||||
and do not need to be manually configured.
|
||||
|
||||
* rabit_tracker_uri [passed in automatically by tracker]
|
||||
- The uri/ip of rabit tracker
|
||||
* rabit_tracker_port [passed in automatically by tracker]
|
||||
- The port of rabit tracker
|
||||
* rabit_task_id [automatically detected]
|
||||
- The unique identifier of computing process
|
||||
- When running on Hadoop, this is automatically extracted from environment variable
|
||||
* rabit_reduce_buffer [default = 256MB]
|
||||
- The memory buffer used to store intermediate result of reduction
|
||||
- Format "digits + unit", can be 128M, 1G
|
||||
* rabit_global_replica [default = 5]
|
||||
- Number of replication copies of result kept for each Allreduce/Broadcast call
|
||||
* rabit_local_replica [default = 2]
|
||||
- Number of replication of local model in check point
|
||||
@ -1,3 +0,0 @@
|
||||
numpy
|
||||
breathe
|
||||
commonmark
|
||||
@ -1,11 +0,0 @@
|
||||
Python API of Rabit
|
||||
===================
|
||||
This page contains document of python API of rabit.
|
||||
|
||||
```eval_rst
|
||||
.. toctree::
|
||||
|
||||
.. automodule:: rabit
|
||||
:members:
|
||||
:show-inheritance:
|
||||
```
|
||||
@ -1,16 +0,0 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Helper utilty function for customization."""
|
||||
import sys
|
||||
import os
|
||||
import docutils
|
||||
import subprocess
|
||||
|
||||
if os.environ.get('READTHEDOCS', None) == 'True':
|
||||
subprocess.call('cd ..; rm -rf recommonmark;' +
|
||||
'git clone https://github.com/tqchen/recommonmark', shell=True)
|
||||
|
||||
sys.path.insert(0, os.path.abspath('../recommonmark/'))
|
||||
from recommonmark import parser, transform
|
||||
|
||||
MarkdownParser = parser.CommonMarkParser
|
||||
AutoStructify = transform.AutoStructify
|
||||
@ -1,26 +0,0 @@
|
||||
export CC = gcc
|
||||
export CXX = g++
|
||||
export MPICXX = mpicxx
|
||||
export LDFLAGS= -pthread -lm -L../lib
|
||||
export CFLAGS = -Wall -O3 -msse2 -std=c++11 -Wno-unknown-pragmas -fPIC -fopenmp -I../include
|
||||
|
||||
.PHONY: clean all lib libmpi
|
||||
BIN = basic.rabit broadcast.rabit
|
||||
MOCKBIN= lazy_allreduce.mock
|
||||
|
||||
all: $(BIN)
|
||||
basic.rabit: basic.cc lib ../lib/librabit.a
|
||||
broadcast.rabit: broadcast.cc lib ../lib/librabit.a
|
||||
lazy_allreduce.mock: lazy_allreduce.cc lib ../lib/librabit.a
|
||||
|
||||
$(BIN) :
|
||||
$(CXX) $(CFLAGS) -o $@ $(filter %.cpp %.o %.c %.cc %.a, $^) $(LDFLAGS)
|
||||
|
||||
$(MOCKBIN) :
|
||||
$(CXX) $(CFLAGS) -std=c++11 -o $@ $(filter %.cpp %.o %.c %.cc, $^) $(LDFLAGS) -lrabit_mock
|
||||
|
||||
$(OBJ) :
|
||||
$(CXX) -c $(CFLAGS) -o $@ $(firstword $(filter %.cpp %.c %.cc, $^) )
|
||||
|
||||
clean:
|
||||
$(RM) $(OBJ) $(BIN) $(MOCKBIN) *~ ../src/*~
|
||||
@ -1 +0,0 @@
|
||||
See tutorial at ../doc/guide.md
|
||||
@ -1,35 +0,0 @@
|
||||
/*!
|
||||
* Copyright (c) 2014 by Contributors
|
||||
* \file basic.cc
|
||||
* \brief This is an example demonstrating what is Allreduce
|
||||
*
|
||||
* \author Tianqi Chen
|
||||
*/
|
||||
#define _CRT_SECURE_NO_WARNINGS
|
||||
#define _CRT_SECURE_NO_DEPRECATE
|
||||
#include <vector>
|
||||
#include <rabit/rabit.h>
|
||||
using namespace rabit;
|
||||
int main(int argc, char *argv[]) {
|
||||
int N = 3;
|
||||
if (argc > 1) {
|
||||
N = atoi(argv[1]);
|
||||
}
|
||||
std::vector<int> a(N);
|
||||
rabit::Init(argc, argv);
|
||||
for (int i = 0; i < N; ++i) {
|
||||
a[i] = rabit::GetRank() + i;
|
||||
}
|
||||
printf("@node[%d] before-allreduce: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
// allreduce take max of each elements in all processes
|
||||
Allreduce<op::Max>(&a[0], N);
|
||||
printf("@node[%d] after-allreduce-max: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
// second allreduce that sums everything up
|
||||
Allreduce<op::Sum>(&a[0], N);
|
||||
printf("@node[%d] after-allreduce-sum: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
rabit::Finalize();
|
||||
return 0;
|
||||
}
|
||||
@ -1,27 +0,0 @@
|
||||
#!/usr/bin/python
|
||||
"""
|
||||
demo python script of rabit
|
||||
"""
|
||||
from __future__ import print_function
|
||||
from builtins import range
|
||||
import os
|
||||
import sys
|
||||
import numpy as np
|
||||
# import rabit, the tracker script will setup the lib path correctly
|
||||
# for normal run without tracker script, add following line
|
||||
# sys.path.append(os.path.dirname(__file__) + '/../python')
|
||||
import rabit
|
||||
|
||||
rabit.init()
|
||||
n = 3
|
||||
rank = rabit.get_rank()
|
||||
a = np.zeros(n)
|
||||
for i in range(n):
|
||||
a[i] = rank + i
|
||||
|
||||
print('@node[%d] before-allreduce: a=%s' % (rank, str(a)))
|
||||
a = rabit.allreduce(a, rabit.MAX)
|
||||
print('@node[%d] after-allreduce-max: a=%s' % (rank, str(a)))
|
||||
a = rabit.allreduce(a, rabit.SUM)
|
||||
print('@node[%d] after-allreduce-sum: a=%s' % (rank, str(a)))
|
||||
rabit.finalize()
|
||||
@ -1,16 +0,0 @@
|
||||
#include <rabit/rabit.h>
|
||||
using namespace rabit;
|
||||
const int N = 3;
|
||||
int main(int argc, char *argv[]) {
|
||||
rabit::Init(argc, argv);
|
||||
std::string s;
|
||||
if (rabit::GetRank() == 0) s = "hello world";
|
||||
printf("@node[%d] before-broadcast: s=\"%s\"\n",
|
||||
rabit::GetRank(), s.c_str());
|
||||
// broadcast s from node 0 to all other nodes
|
||||
rabit::Broadcast(&s, 0);
|
||||
printf("@node[%d] after-broadcast: s=\"%s\"\n",
|
||||
rabit::GetRank(), s.c_str());
|
||||
rabit::Finalize();
|
||||
return 0;
|
||||
}
|
||||
@ -1,23 +0,0 @@
|
||||
#!/usr/bin/python
|
||||
"""
|
||||
demo python script of rabit
|
||||
"""
|
||||
from __future__ import print_function
|
||||
import os
|
||||
import sys
|
||||
# add path to wrapper
|
||||
# for normal run without tracker script, add following line
|
||||
# sys.path.append(os.path.dirname(__file__) + '/../wrapper')
|
||||
import rabit
|
||||
|
||||
rabit.init()
|
||||
n = 3
|
||||
rank = rabit.get_rank()
|
||||
s = None
|
||||
if rank == 0:
|
||||
s = {'hello world':100, 2:3}
|
||||
print('@node[%d] before-broadcast: s=\"%s\"' % (rank, str(s)))
|
||||
s = rabit.broadcast(s, 0)
|
||||
|
||||
print('@node[%d] after-broadcast: s=\"%s\"' % (rank, str(s)))
|
||||
rabit.finalize()
|
||||
@ -1,34 +0,0 @@
|
||||
/*!
|
||||
* Copyright (c) 2014 by Contributors
|
||||
* \file basic.cc
|
||||
* \brief This is an example demonstrating what is Allreduce
|
||||
*
|
||||
* \author Tianqi Chen
|
||||
*/
|
||||
#include <rabit/rabit.h>
|
||||
|
||||
using namespace rabit;
|
||||
const int N = 3;
|
||||
int main(int argc, char *argv[]) {
|
||||
int a[N] = {0};
|
||||
rabit::Init(argc, argv);
|
||||
// lazy preparation function
|
||||
auto prepare = [&]() {
|
||||
printf("@node[%d] run prepare function\n", rabit::GetRank());
|
||||
for (int i = 0; i < N; ++i) {
|
||||
a[i] = rabit::GetRank() + i;
|
||||
}
|
||||
};
|
||||
printf("@node[%d] before-allreduce: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
// allreduce take max of each elements in all processes
|
||||
Allreduce<op::Max>(&a[0], N, prepare);
|
||||
printf("@node[%d] after-allreduce-sum: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
// rum second allreduce
|
||||
Allreduce<op::Sum>(&a[0], N);
|
||||
printf("@node[%d] after-allreduce-max: a={%d, %d, %d}\n",
|
||||
rabit::GetRank(), a[0], a[1], a[2]);
|
||||
rabit::Finalize();
|
||||
return 0;
|
||||
}
|
||||
@ -1,31 +0,0 @@
|
||||
#!/usr/bin/python
|
||||
"""
|
||||
demo python script of rabit: Lazy preparation function
|
||||
"""
|
||||
import os
|
||||
import sys
|
||||
import numpy as np
|
||||
# import rabit, the tracker script will setup the lib path correctly
|
||||
# for normal run without tracker script, add following line
|
||||
# sys.path.append(os.path.dirname(__file__) + '/../wrapper')
|
||||
import rabit
|
||||
|
||||
|
||||
# use mock library so that we can run failure test
|
||||
rabit.init(lib = 'mock')
|
||||
n = 3
|
||||
rank = rabit.get_rank()
|
||||
a = np.zeros(n)
|
||||
|
||||
def prepare(a):
|
||||
print('@node[%d] run prepare function' % rank)
|
||||
# must take in reference and modify the reference
|
||||
for i in range(n):
|
||||
a[i] = rank + i
|
||||
|
||||
print('@node[%d] before-allreduce: a=%s' % (rank, str(a)))
|
||||
a = rabit.allreduce(a, rabit.MAX, prepare_fun = prepare)
|
||||
print('@node[%d] after-allreduce-max: a=%s' % (rank, str(a)))
|
||||
a = rabit.allreduce(a, rabit.SUM)
|
||||
print('@node[%d] after-allreduce-sum: a=%s' % (rank, str(a)))
|
||||
rabit.finalize()
|
||||
Loading…
x
Reference in New Issue
Block a user