From b3fdb3729f597a2e2dd951f79d4d494ef6203a73 Mon Sep 17 00:00:00 2001 From: Andreas Kloeckner Date: Thu, 11 Jul 2013 17:26:20 -0400 Subject: [PATCH] Add struct howto to docs --- .gitignore | 1 + doc/Makefile | 116 ++++++++++++++++++++++++++--------- doc/source/_static/akdoc.css | 2 +- doc/source/conf.py | 1 + doc/source/howto.rst | 103 +++++++++++++++++++++++++++++++ doc/source/index.rst | 1 + doc/upload-docs.sh | 3 +- 7 files changed, 194 insertions(+), 33 deletions(-) create mode 100644 doc/source/howto.rst diff --git a/.gitignore b/.gitignore index 5cdaf06d..066262ad 100644 --- a/.gitignore +++ b/.gitignore @@ -48,3 +48,4 @@ setuptools.pth distribute-*.tar.gz core *.sess +_build diff --git a/doc/Makefile b/doc/Makefile index 2b787d23..d03f64d1 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -5,22 +5,34 @@ SPHINXOPTS = SPHINXBUILD = python `which sphinx-build` PAPER = +BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -.PHONY: help clean html web pickle htmlhelp latex changes linkcheck +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest help: @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " pickle to make pickle files (usable by e.g. sphinx-web)" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " changes to make an overview over all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" + @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 " 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 " text to make text files" + @echo " man to make manual pages" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" +.PHONY: help clean html web pickle htmlhelp latex changes linkcheck constants: python make_constants.py > source/constants.inc @@ -29,45 +41,89 @@ clean: -rm -rf build/* html: constants - mkdir -p build/html build/doctrees source/.static - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo - @echo "Build finished. The HTML pages are in build/html." + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +singlehtml: constants + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: constants - mkdir -p build/pickle build/doctrees - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo - @echo "Build finished; now you can process the pickle files or run" - @echo " sphinx-web build/pickle" - @echo "to start the sphinx-web server." + @echo "Build finished; now you can process the pickle files." -web: pickle +json: constants + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." htmlhelp: constants - mkdir -p build/htmlhelp build/doctrees - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in build/htmlhelp." + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: constants + $(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/loopy.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/loopy.qhc" + +devhelp: constants + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/loopy" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/loopy" + @echo "# devhelp" + +epub: constants + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: constants - mkdir -p build/latex build/doctrees - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/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: constants + $(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." + +text: constants + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: constants + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo - @echo "Build finished; the LaTeX files are in build/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." changes: constants - mkdir -p build/changes build/doctrees - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo - @echo "The overview file is in build/changes." + @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: constants - mkdir -p build/linkcheck build/doctrees - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ - "or in build/linkcheck/output.txt." + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: constants + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/doc/source/_static/akdoc.css b/doc/source/_static/akdoc.css index e83c3b72..1a1ef7a6 100644 --- a/doc/source/_static/akdoc.css +++ b/doc/source/_static/akdoc.css @@ -1,5 +1,5 @@ pre { - line-height: 100%; + line-height: 110%; } .footer { diff --git a/doc/source/conf.py b/doc/source/conf.py index 8b10c70c..555d0b87 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -26,6 +26,7 @@ extensions = [ 'sphinx.ext.intersphinx', 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', ] # Add any paths that contain templates here, relative to this directory. diff --git a/doc/source/howto.rst b/doc/source/howto.rst new file mode 100644 index 00000000..4a35bba5 --- /dev/null +++ b/doc/source/howto.rst @@ -0,0 +1,103 @@ +How-tos +======= + +How to use struct types with PyOpenCL +------------------------------------- + +We import and initialize PyOpenCL as usual: + +.. doctest:: + :options: +ELLIPSIS + + >>> import numpy as np + >>> import pyopencl as cl + >>> import pyopencl.tools + >>> import pyopencl.array + + >>> ctx = cl.create_some_context(interactive=False) + >>> queue = cl.CommandQueue(ctx) + +Then, suppose we would like to declare a struct consisting of an integer and a +floating point number. We first create a :class:`numpy.dtype` along these +lines: + +.. doctest:: + + >>> my_struct = np.dtype([("field1", np.int32), ("field2", np.float32)]) + >>> print my_struct + [('field1', '`_. So as a first step, we +match our dtype against CL's version: + +.. doctest:: + + >>> my_struct, my_struct_c_decl = cl.tools.match_dtype_to_c_struct( + ... ctx.devices[0], "my_struct", my_struct) + >>> print my_struct_c_decl + typedef struct { + int field1; + float field2; + } my_struct; + + + +We then tell PyOpenCL about our new type. + +.. doctest:: + + >>> my_struct = cl.tools.get_or_register_dtype("my_struct", my_struct) + +Next, we can create some data of that type on the host and transfer it to +the device: + +.. doctest:: + + >>> ary_host = np.empty(20, my_struct) + >>> ary_host["field1"].fill(217) + >>> ary_host["field2"].fill(1000) + >>> ary_host[13]["field2"] = 12 + >>> print ary_host + [(217, 1000.0) (217, 1000.0) (217, 1000.0) (217, 1000.0) (217, 1000.0) + (217, 1000.0) (217, 1000.0) (217, 1000.0) (217, 1000.0) (217, 1000.0) + (217, 1000.0) (217, 1000.0) (217, 1000.0) (217, 12.0) (217, 1000.0) + (217, 1000.0) (217, 1000.0) (217, 1000.0) (217, 1000.0) (217, 1000.0)] + + >>> ary = cl.array.to_device(queue, ary_host) + +We can then operate on the array with our own kernels: + +.. doctest:: + + >>> prg = cl.Program(ctx, my_struct_c_decl + """ + ... __kernel void set_to_1(__global my_struct *a) + ... { + ... a[get_global_id(0)].field1 = 1; + ... } + ... """).build() + + >>> evt = prg.set_to_1(queue, ary.shape, None, ary.data) + >>> print ary + [(1, 1000.0) (1, 1000.0) (1, 1000.0) (1, 1000.0) (1, 1000.0) (1, 1000.0) + (1, 1000.0) (1, 1000.0) (1, 1000.0) (1, 1000.0) (1, 1000.0) (1, 1000.0) + (1, 1000.0) (1, 12.0) (1, 1000.0) (1, 1000.0) (1, 1000.0) (1, 1000.0) + (1, 1000.0) (1, 1000.0)] + +as well as with PyOpenCL's built-in operations: + + >>> from pyopencl.elementwise import ElementwiseKernel + >>> elwise = ElementwiseKernel(ctx, "my_struct *a", "a[i].field1 = 2;", + ... preamble=my_struct_c_decl) + >>> evt = elwise(ary) + >>> print ary + [(2, 1000.0) (2, 1000.0) (2, 1000.0) (2, 1000.0) (2, 1000.0) (2, 1000.0) + (2, 1000.0) (2, 1000.0) (2, 1000.0) (2, 1000.0) (2, 1000.0) (2, 1000.0) + (2, 1000.0) (2, 12.0) (2, 1000.0) (2, 1000.0) (2, 1000.0) (2, 1000.0) + (2, 1000.0) (2, 1000.0)] diff --git a/doc/source/index.rst b/doc/source/index.rst index 607b9da5..60ff9f3e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -75,6 +75,7 @@ is on the web, thanks to Ian Johnson. runtime array algorithm + howto tools misc diff --git a/doc/upload-docs.sh b/doc/upload-docs.sh index 40d95150..47735a29 100755 --- a/doc/upload-docs.sh +++ b/doc/upload-docs.sh @@ -1,4 +1,3 @@ #! /bin/sh -cp build/html/runtime.html build/html/reference.html -rsync --progress --verbose --archive --delete build/html/* doc-upload:doc/pyopencl +rsync --progress --verbose --archive --delete _build/html/* doc-upload:doc/pyopencl -- GitLab