Skip to content

Commit 8f31ac2

Browse files
author
Martin Ruefenacht
committed
Initial commit
0 parents  commit 8f31ac2

34 files changed

+3712
-0
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
**/__pycache__
2+
**/make.bat
3+
**/_build

‎LICENSE

Whitespace-only changes.

‎README.md

Whitespace-only changes.

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/callbacks.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
=========
2+
CALLBACKS
3+
=========

‎docs/conf.py

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
import os
14+
import sys
15+
16+
sys.path.insert(0, os.path.abspath("../../.."))
17+
18+
19+
# -- Project information -----------------------------------------------------
20+
21+
project = "pympistandard"
22+
copyright = "2021, Martin Ruefenacht"
23+
author = "Martin Ruefenacht"
24+
25+
26+
# -- General configuration ---------------------------------------------------
27+
28+
# Add any Sphinx extension module names here, as strings. They can be
29+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
30+
# ones.
31+
extensions = [
32+
"sphinx.ext.autodoc",
33+
"sphinx.ext.napoleon",
34+
"myst_parser",
35+
]
36+
37+
# Add any paths that contain templates here, relative to this directory.
38+
templates_path = ["_templates"]
39+
40+
# List of patterns, relative to source directory, that match files and
41+
# directories to ignore when looking for source files.
42+
# This pattern also affects html_static_path and html_extra_path.
43+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
44+
45+
source_suffix = {".rst": "restructuredtext", ".txt": "markdown", ".md": "markdown"}
46+
47+
48+
# -- Options for HTML output -------------------------------------------------
49+
50+
# The theme to use for HTML and HTML Help pages. See the documentation for
51+
# a list of builtin themes.
52+
#
53+
html_theme = "sphinx_rtd_theme"
54+
55+
# Add any paths that contain custom static files (such as style sheets) here,
56+
# relative to this directory. They are copied after the builtin static files,
57+
# so a file named "default.css" will overwrite the builtin "default.css".
58+
html_static_path = ["_static"]
59+
60+
61+
add_module_names = False
62+
63+
64+
autodoc_default_options = {
65+
"show-inheritance": True,
66+
"members": True,
67+
"inherited-members": True,
68+
"special-members": "__str__",
69+
}

‎docs/index.rst

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
Python API to the MPI Standard
2+
##############################
3+
4+
This tutorial is intended to teach how to use the Python API of the MPI Standard.
5+
6+
Structure of the MPI Standard
7+
*****************************
8+
9+
The Python usage in the MPI Standard is varied.
10+
11+
The Python Domain Specific Language (DSL): We use the DSL to specify and encode the information in the MPI Standard through *mpi-binding* latex blocks. This facilitates that the "truth" remains within the Latex of the Standard.
12+
13+
The Python API *pympistandard* (./pympistandard) is the package by which access to the DSL encoded information is given to tools.
14+
15+
The tools which operate on the DSL encoded information are also written in Python (although they could be written in any language). This includes the binding_prepass (binding-tool/binding_prepass), binding_tool (tools/binding_tool), binding_linter (binding-tool/binding_linter), etc.
16+
17+
Finally, the testing of both the binding_tool, DSL, and text of the MPI Standard are partially done in Python (test/).
18+
19+
How to start using the Python API
20+
*********************************
21+
22+
The goal of the Python API is to provide access to all information in the MPI Standard as easily as possible. Therefore importing the pympistandard package is done the typical python way, either by exporting the PYTHONPATH or having the pympistandard package on a standard path. The current solution is to have PYTHONPATH correctly exported.
23+
24+
To have functioning setup do:
25+
26+
#. change directory to the mpi-standard directory containing the version which you want to access programatically
27+
#. ``make`` (at least past the rendering such that the apis.json file exists)
28+
#. ``export PYTHONPATH=$(pwd)``
29+
30+
At this point the following should be possible within a python interpreter:
31+
32+
.. sourcecode::
33+
34+
import pympistandard
35+
36+
.. toctree::
37+
:maxdepth: 2
38+
39+
procedure
40+
41+
The Python API
42+
**************
43+
44+
After importing the pympistandard package no information is yet loaded. One must first do:
45+
46+
.. sourcecode::
47+
48+
pympistandard.use_api_version(1)
49+
50+
This loads the information contained in the MPI Standard using the first API version.
51+
52+
In future, other versions of the API will be accessible and a deprecation warning will be given. Extensions will not merit a new version, only backwards compatibility breaking changes. Once the ``use_api_version`` has been called the information is read into the global variables, at which point all information in the Standard will be accessible.
53+
54+
.. sourcecode::
55+
56+
import pympistandard as std
57+
std.use_api_version(1)
58+
59+
The top-level package contains **PROCEDURES**, **KINDS**, **CALLBACKS**, **PREDEFINED_FUNCTIONS** (the names are subject to change).
60+
61+
* PROCEDURES are all MPI procedures such as MPI_Send, MPI_Wait, MPI_Allreduce, MPI_Init, ...
62+
* KINDS are all the different KINDS which are currently specified within the MPI Standard (these are subject to major revisions)
63+
* CALLBACKS are all callback functions which are given as Kinds, these provide access to the expressions instead of just a label like the corresponding KIND
64+
* PREDEFINED_FUNCTIONS are the predefined callback functions provided by the MPI Standard and its implementations
65+
66+
Using the Python API
67+
********************
68+
69+
The global containers can be accessed using the dot notation or the dictionary access:
70+
71+
.. sourcecode::
72+
73+
mpi_send = std.PROCEDURES.mpi_send
74+
75+
mpi_send = std.PROCEDURES["mpi_send"]
76+
77+
Capitalisation is ignored. `MPI_SEND` is the same as `mpi_send`.
78+
79+
Checking membership of in a container can be done with:
80+
81+
.. sourcecode::
82+
83+
"mpi_send" in std.PROCEDURES
84+
mpi_send in std.PROCEDURES
85+
86+
Another method to fetch Procedure/Callback/PredefinedFunction objects is through the provided iterators. Iterators are currently available for all Procedures expressible in a given language:
87+
88+
.. sourcecode::
89+
90+
count_initializing_iso_c_procedures = sum(procedure.express.iso_c.is_initializing() for procedure in std.all_iso_c_procedures())
91+
92+
*Currently, is_initializing does not exist.*
93+
94+
Language Agnostic Information
95+
*****************************
96+
97+
The above `mpi_send` object is a Procedure object which encapsulates all information which is generic to the MPI Procedure MPI\_Send. In future this will include all sorts of information such as the initialising, starting, completing, and freeing behaviour of a specific procedure. Currently the properties are `has_embiggenment` and `has_proxy_render`.
98+
99+
Language Expressions
100+
********************
101+
102+
In addition to language agnostic information about the MPI Procedure the object provides access to expressions of the Procedure. An expression is a form of the Procedure in a specific language officially standardised by the MPI Forum through the MPI Standard. To access the ISO C expression of the _MPI\_Send_ procedure you would do:
103+
104+
.. sourcecode::
105+
106+
c_send = std.PROCEDURES.mpi_send.express.iso_c
107+
108+
The `c\_send` object is a ISOCProcedure. The language specific procedure objects allow access to properties which are specific to a language. For example, ISO C procedures may use uppercase indexing in the MPI Standard therefore the `has_uppercase_index` property is provided within the ISOCProcedure.
109+
110+
In addition to language specific properties the expression in the language is enabled through this object. Access to parameters, return type/kind, and name is given:
111+
112+
.. sourcecode::
113+
114+
c_send.name # 'MPI_Send'
115+
c_send.return_type # 'int'
116+
117+
Parameters are accessed as objects themselves:
118+
119+
.. sourcecode::
120+
121+
names = (parameter.name for parameter in c_send.parameters) # ('buf', 'count', 'datatype', 'dest', 'tag', 'comm')
122+
123+
Parameters also provide all properties associated with them and can be access through the object.
124+
125+
Not all Procedures are expressed in all languages. Therefore when an attempt is made to access an expression which does not exist a Nonetype is returned:
126+
127+
.. sourcecode::
128+
129+
std.PROCEDURES.mpi_sizeof.iso_c # None
130+
131+
Other Expressions
132+
*****************
133+
134+
The expressions are not only related to the language in which a binding is expressed, but also the type of binding. For example, the profiling interface of MPI specifies many PMPI prefixed procedures which can be accessed through:
135+
136+
.. sourcecode::
137+
138+
pmpi_send = std.PROCEDURES.mpi_send.profile.iso_c
139+
pmpi_send.name # 'PMPI_Send'
140+
141+
Another large expression subset is the embiggened procedures:
142+
143+
.. sourcecode::
144+
145+
mpi_send_c = std.PROCEDURES.mpi_send.embiggen.iso_c
146+
mpi_send_c.name # 'MPI_Send_c'
147+
148+
These expression attributes can be combined arbitrarily: `mpi_send.profile.embiggen.iso_c`. If a valid configuration is chosen an object representing the properties and expression will be returned. If not a Nonetype will be returned.
149+
150+
Instead of accessing the expressions through the dot notation you can also choose to have an iterable over all expressions of a language:
151+
152+
.. sourcecode::
153+
154+
print(std.PROCEDURES.mpi_send.express.all_iso_c)
155+
156+
# (<pympistandard.isoc.ISOCProcedure object at 0x10ee9ef10>,
157+
# <pympistandard.isoc.ProfilingISOCProcedure object at 0x10ee9eeb0>,
158+
# <pympistandard.isoc.EmbiggenedISOCProcedure object at 0x10ee9ed30>,
159+
# <pympistandard.isoc.EmbiggenedProfilingISOCProcedure object at 0x10ee9ed90>)

‎docs/kind.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
====
2+
Kind
3+
====
4+
5+
A Kind represents a language agnostic type for the MPI Standard. It is used as a type for parameters and return types of all Procedures, Callbacks, and Predefined Functions.
6+
7+
All Kinds are available
8+
9+
.. autoclass:: pympistandard.kind.Kind
10+
11+
.. autoclass:: pympistandard.kind.PolyKind
12+
13+
.. autoclass:: pympistandard.kind.CPTRKind

‎docs/kinds.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
=====
2+
KINDS
3+
=====
4+
5+
.. automodule:: pympistandard._kinds
6+
:ignore-module-all:

‎docs/parameters.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
==========
2+
Parameters
3+
==========
4+
5+

0 commit comments

Comments
 (0)