Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates to Python bindings and missed API #292

Merged
merged 7 commits into from
Oct 7, 2020
Merged

Updates to Python bindings and missed API #292

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
85fd816
First cut at acknowledgements
rhc54 Oct 2, 2020
867f8c5
Acknowledgements: Fix typo, sync with v3.2
jjhursey Oct 2, 2020
56bb4e5
Updates to Python bindings and missed API
rhc54 Oct 3, 2020
ac8bccb
Update revisions
rhc54 Oct 3, 2020
cfbf42a
Ensure all attributes are referenced at least once
rhc54 Oct 3, 2020
7cc7071
Cleanups in Python bindings
rhc54 Oct 5, 2020
4aef4e3
Per WG, avoid use of term "slot"
rhc54 Oct 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 31 additions & 3 deletions Acknowledgements.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,39 @@ \section{Version 4.0}
The following list includes some of the active participants in the PMIx v4 standardization process.

\begin{itemize}
\item \ldots
\item Ralph H. Castain and Danielle Sikich
\item Joshua Hursey and David Solt
\item Dirk Schubert
\item John DelSignore
\item Aurelien Bouteiller
\item Michael A Raymond
\item Howard Pritchard and Nathan Hjelm
\item Brice Goglin
\item Kathryn Mohror and Stephen Herbein
\item Thomas Naughton and Swaroop Pophale
\item William E. Allcock and Paul Rich
\item Michael Karo
\item Artem Polyakov
\end{itemize}

The following institutions supported this effort through time and travel support for the people listed above.

\begin{itemize}
\item \ldots
\item Intel Corporation
\item IBM, Inc.
\item Allinea (ARM)
\item Perforce
\item University of Tennessee, Knoxville
\item The Exascale Computing Project, an initiative of the US Department of Energy
\item National Science Foundation
\item HPE Co.
\item Los Alamos National Laboratory
\item INRIA
\item Lawrence Livermore National Laboratory
\item Oak Ridge National Laboratory
\item Argonne National Laboratory
\item Altair
\item NVIDIA
\end{itemize}

%%%%%%%%%% Version 3.0
Expand All @@ -30,10 +56,11 @@ \section{Version 3.0}

\begin{itemize}
\item Ralph H. Castain, Andrew Friedley, Brandon Yates
\item Joshua Hursey
\item Joshua Hursey and David Solt
\item Aurelien Bouteiller and George Bosilca
\item Dirk Schubert
\item Kevin Harms
\item Artem Polyakov
\end{itemize}

The following institutions supported this effort through time and travel support for the people listed above.
Expand All @@ -46,6 +73,7 @@ \section{Version 3.0}
\item National Science Foundation
\item Argonne National Laboratory
\item Allinea (ARM)
\item NVIDIA
\end{itemize}

%%%%%%%%%% Version 2.0
Expand Down
174 changes: 35 additions & 139 deletions App_Python.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,9 @@ \section{Datatype Definitions}
\refstruct{pmix_proc_state_t} & PMIX_PROC_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline
\refstruct{pmix_proc_info_t} & PMIX_PROC_INFO & \{'proc': \{'nspace': nspace, 'rank': rank\}, 'hostname': hostname, 'executable': executable, 'pid': pid, 'exitcode': exitcode, 'state': state\} & \refarg{proc} is a Python \refpy{proc} dictionary; \refarg{hostname} and \refarg{executable} are Python strings; and \refarg{pid}, \refarg{exitcode}, and \refarg{state} are Python integers \\ \hline
\refstruct{pmix_data_array_t} & PMIX_DATA_ARRAY & \pylabel{array}\{'type': type, 'array': array\} & \refarg{type} is the \ac{PMIx} type of object in the array and \refarg{array} is a Python \emph{list} containing the individual array elements. Note that \refarg{array} can consist of \emph{any} \ac{PMIx} types, including (for example) a Python \refpy{info} object that itself contains an \refpy{array} value \\ \hline
\refstruct{pmix_info_directives_t} & PMIX_INFO_DIRECTIVES & \pylabel{info directives}bitarray & 32-bit array \\ \hline
\refstruct{pmix_info_directives_t} & PMIX_INFO_DIRECTIVES & \pylabel{info directives}list & list of integer values (defined in Section \ref{api:struct:infodirs}) \\ \hline
\refstruct{pmix_alloc_directive_t} & PMIX_ALLOC_DIRECTIVE & \pylabel{allocdir}integer & value shall be limited to the \code{uint8_t} range \\ \hline
\refstruct{pmix_iof_channel_t} & PMIX_IOF_CHANNEL & \pylabel{channel}bitarray & 16-bit array \\ \hline
\refstruct{pmix_iof_channel_t} & PMIX_IOF_CHANNEL & \pylabel{channel}list & list of integer values (defined in Section \ref{api:tool:iofchannels}) \\ \hline
\refstruct{pmix_envar_t} & PMIX_ENVAR & \{'envar': envar, 'value': value, 'separator': separator\} & \refarg{envar} and \refarg{value} are Python strings, and \refarg{separator} a single-character Python string \\ \hline
\refstruct{pmix_value_t} & PMIX_VALUE & \pylabel{value}\{'value': value, 'val_type': type\} & \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline
\refstruct{pmix_info_t} & PMIX_INFO & \pylabel{info}\{'key': key, 'flags': flags, value': value, 'val_type': type\} & \refarg{key} is a Python string \refpy{key}, \refarg{flags} is an \refpy{info directives} value, \refarg{type} is the \ac{PMIx} datatype of \refarg{value}, and \refarg{value} is the associated value expressed in the appropriate Python form for the specified datatype \\ \hline
Expand All @@ -86,15 +86,15 @@ \section{Datatype Definitions}
\refstruct{pmix_regattr_t} & PMIX_REGATTR & \pylabel{regattr}\{'name': name, 'key': key, 'type': type, 'info': [info], 'description': [desc]\} & \refarg{name} and \refarg{string} are Python strings; \refarg{type} is the \ac{PMIx} datatype for the attribute's value; \refarg{info} is a Python \emph{list} of \refpy{info} values; and \refarg{description} is a list of Python strings describing the attribute \\ \hline
\refstruct{pmix_job_state_t} & PMIX_JOB_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline
\refstruct{pmix_link_state_t} & PMIX_LINK_STATE & integer & value shall be limited to the \code{uint8_t} range \\ \hline
\refstruct{pmix_cpuset_t} & PMIX_PROC_CPUSET & \pylabel{cpuset}\{'source': source, 'cpus': bitmap\} & \refarg{source} is a string name of the library that created the cpuset; and \refarg{cpus} is a bitarray containing the cpuset \\ \hline
\refstruct{pmix_locality_t} & PMIX_LOCTYPE & \pylabel{locality}bitarray & 16-bit array containing the relative locality of the specified local process \\ \hline
\refstruct{pmix_cpuset_t} & PMIX_PROC_CPUSET & \pylabel{cpuset}\{'source': source, 'cpus': bitmap\} & \refarg{source} is a string name of the library that created the cpuset; and \refarg{cpus} is a list of string ranges identifying the \acp{PU} to which the process is bound (e.g., [1, 3-5, 7]) \\ \hline
\refstruct{pmix_locality_t} & PMIX_LOCTYPE & \pylabel{locality}list & list of integer values (defined in Section \ref{api:proc:locality}) describing the relative locality of the specified local process \\ \hline
\refstruct{pmix_fabric_t} & N/A & \pylabel{fabric}\{'name': name, 'index': idx, 'info': [info]\} & \refarg{name} is the string name assigned to the fabric; \refarg{index} is the integer ID assigned to the fabric; \refarg{info} is a list of \refpy{info} describing the fabric \\ \hline
\refstruct{pmix_endpoint_t} & PMIX_ENDPOINT & \pylabel{endpoint}\{'uuid': uuid, 'osname': osname, endpt': endpt\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; \refarg{endpt} is a \refpy{byteobject} containing the endpoint information \\ \hline
\refstruct{pmix_device_distance_t} & PMIX_DEVICE_DIST & \pylabel{devdist}\{'uuid': uuid, 'osname': osname, mindist': mindist, 'maxdist': maxdist\} & \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{mindist} and \refarg{maxdist} are Python integers \\ \hline
\refstruct{pmix_coord_t} & PMIX_COORD & \pylabel{coord}\{'view': view, 'coord': [coords]\} & \refarg{view} is the \refstruct{pmix_coord_view_t} of the coordinate; and \refarg{coord} is a list of integer coordinates, one for each dimension of the fabric \\ \hline
\refstruct{pmix_geometry_t} & PMIX_GEOMETRY & \pylabel{geometry}\{'fabric': idx, 'uuid': uuid, 'osname': osname, coordinates': [coords]\} & \refarg{fabric} is the Python integer index of the fabric; \refarg{uuid} is the string system-unique identifier assigned to the device; \refarg{osname} is the operating system name assigned to the device; and \refarg{coordinates} is a list of \refpy{coord} containing the coordinates for the device across all views \\ \hline
\refstruct{pmix_device_type_t} & PMIX_DEVTYPE & \pylabel{devtype}bitarray & 16-bit array \\ \hline
\refstruct{pmix_bind_envelope_t} & N/A & \pylabel{bindenv}integer & \\ \hline
\refstruct{pmix_device_type_t} & PMIX_DEVTYPE & \pylabel{devtype}list & list of integer values (defined in Section \ref{api:proc:devtype}) \\ \hline
\refstruct{pmix_bind_envelope_t} & N/A & \pylabel{bindenv}integer & one of the values defined in Section \ref{api:proc:bindenv} \\ \hline
\end{longtable}
\end{small}
\end{landscape}
Expand Down Expand Up @@ -2335,7 +2335,7 @@ \subsection{Client.load_topology}
\item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\end{itemize}

See \refapi{PMIx_Load_topology} for details - note that the topology loaded into the \ac{PMIx} library may be utilized by \ac{PMIx} and other libraries, but is not accessible by Python.
See \refapi{PMIx_Load_topology} for details - note that the topology loaded into the \ac{PMIx} library may be utilized by \ac{PMIx} and other libraries, but is not directly accessible by Python.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Expand Down Expand Up @@ -2364,43 +2364,12 @@ \subsection{Client.get_relative_locality}

\begin{itemize}
\item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\item \refarg{locality} - \refpy{locality} bitarray containing the relative locality of the two processes (bitarray)
\item \refarg{locality} - \refpy{locality} list containing the relative locality of the two processes (list)
\end{itemize}

See \refapi{PMIx_Get_relative_locality} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.parse_cpuset_string}
\declareapibinding{PMIxClient.parse_cpuset_string}{PMIx_Parse_cpuset_string}{Python}

\summary
Parse the \ac{PU} binding bitmap from its string representation.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,cpuset = myclient.parse_cpuset_string(cpusetstr:str)
\end{codepar}
\pyspecificend

\begin{arglist}
\argin{cpusetstr}{String of a cpuset (str)}
\end{arglist}


Returns:

\begin{itemize}
\item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\item \refarg{cpuset} - \refpy{cpuset} containing the source and bitmap of the cpuset (dict)
\end{itemize}

See \refapi{PMIx_Parse_cpuset_string} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.get_cpuset}
\declareapibinding{PMIxClient.get_cpuset}{PMIx_Get_cpuset}{Python}
Expand Down Expand Up @@ -2450,7 +2419,7 @@ \subsection{Client.compute_distances}

\begin{arglist}
\argin{cpuset}{\refpy{cpuset} describing the location of the process (dict)}
\argin{info}{List of \refpy{info} dictionaries describing the devices whose distance is to be computed (str)}
\argin{info}{List of \refpy{info} dictionaries describing the devices whose distance is to be computed (list)}
\end{arglist}


Expand All @@ -2461,7 +2430,7 @@ \subsection{Client.compute_distances}
\item \refarg{distances} - List of \refpy{devdist} structures containing the distances from the caller to the specified devices (list)
\end{itemize}

See \refapi{PMIx_Compute_distances} for details.
See \refapi{PMIx_Compute_distances} for details. Note that distances can only be computed against the local topology.



Expand Down Expand Up @@ -2900,6 +2869,28 @@ \subsection{Client.device_type_string}
See \refapi{PMIx_Device_type_string} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Client.progress}
\declareapibinding{PMIxClient.progress}{PMIx_Progress}{Python}

%%%%
\summary

Progress the \ac{PMIx} library.

%%%%
\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
myclient.progress()
\end{codepar}
\pyspecificend


See \refapi{PMIx_Progress} for further details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Expand Down Expand Up @@ -3451,37 +3442,6 @@ \subsection{Server.deliver_inventory}
See \refapi{PMIx_server_deliver_inventory} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.generate_locality_string}
\declareapibinding{PMIxServer.generate_locality_string}{PMIx_server_generate_locality_string}{Python}

\summary
Generate a \ac{PMIx} locality string from a given cpuset.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,locality = myserver.generate_locality_string(cpuset:\refpy{cpuset})
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{cpuset} - Python \refpy{cpuset} identifying the \acp{PU} (\refpy{cpuset})
\end{arglist}

Returns:

\begin{itemize}
\item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\item \refarg{locality} - string representation of the locality corresponding to the provided \refarg{cpuset} (str)
\end{itemize}

See \refapi{PMIx_server_generate_locality_string} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.define_process_set}
\declareapibinding{PMIxServer.define_process_set}{PMIx_server_define_process_set}{Python}
Expand Down Expand Up @@ -3518,20 +3478,19 @@ \subsection{Server.delete_process_set}
\declareapibinding{PMIxServer.delete_process_set}{PMIx_server_delete_process_set}{Python}

\summary
Delete members from a \ac{PMIx} process set.
Delete a \ac{PMIx} process set.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc = myserver.delete_process_set(members:list, name:str)
rc = myserver.delete_process_set(name:str)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{members} - List of Python \refpy{proc} dictionaries identifying the processes to be removed from the process set (list)
\argin{name} - Name of the process set (str)
\end{arglist}

Expand All @@ -3544,68 +3503,6 @@ \subsection{Server.delete_process_set}
See \refapi{PMIx_server_delete_process_set} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.generate_locality_string}
\declareapibinding{PMIxServer.generate_locality_string}{PMIx_server_generate_locality_string}{Python}

\summary
Generate a \ac{PMIx} locality string from a given cpuset.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,locality = myserver.generate_locality_string(cpuset:dict)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{cpuset} - Python \refpy{cpuset} dictionary containing the bitmap of assigned \acp{PU} (dict)
\end{arglist}

Returns:

\begin{itemize}
\item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\item \refarg{locality} - String representation of the \ac{PMIx} locality corresponding to the input bitmap (str)
\end{itemize}

See \refapi{PMIx_server_generate_locality_string} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.generate_cpuset_string}
\declareapibinding{PMIxServer.generate_cpuset_string}{PMIx_server_generate_cpuset_string}{Python}

\summary
Generate a \ac{PMIx} string representation of the provided cpuset.

\format

\versionMarker{4.0}
\pyspecificstart
\begin{codepar}
rc,cpusetstr = myserver.generate_cpuset_string(cpuset:dict)
\end{codepar}
\pyspecificend


\begin{arglist}
\argin{cpuset} - Python \refpy{cpuset} dictionary containing the bitmap of assigned \acp{PU} (dict)
\end{arglist}

Returns:

\begin{itemize}
\item \refarg{rc} - \refconst{PMIX_SUCCESS} or a negative value corresponding to a PMIx error constant (integer)
\item \refarg{cpusetstr} - String representation of the \ac{PMIx} input bitmap (str)
\end{itemize}

See \refapi{PMIx_server_generate_cpuset_string} for details.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Server.register_resources}
\declareapibinding{PMIxServer.register_resources}{PMIx_server_register_resources}{Python}
Expand Down Expand Up @@ -3769,8 +3666,7 @@ \subsection{Tool.attach_to_server}
\declareapibinding{PMIxTool.attach_to_server}{PMIx_tool_attach_to_server}{Python}

\summary
Switch connection from the current \ac{PMIx} server to another one, or initialize a connection to a specified server.

Establish a connection to a PMIx server.

\format

Expand Down
9 changes: 9 additions & 0 deletions Chap_API_Event.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -310,6 +310,15 @@ \subsubsection{Fault tolerance event attributes}
The time in seconds before the \ac{RM} will execute the indicated operation.
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Hybrid programming event attributes}
\label{api:struct:attributes:hybrid}

The following attributes may be used by programming models to coordinate their use of common resources within a process in conjunction with the \refconst{PMIX_OPENMP_PARALLEL_ENTERED} event:
%
\pasteAttributeItem{PMIX_MODEL_PHASE_NAME}
\pasteAttributeItem{PMIX_MODEL_PHASE_TYPE}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Notification Function}
\declareapi{pmix_notification_fn_t}
Expand Down
4 changes: 0 additions & 4 deletions Chap_API_Fabric.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -614,10 +614,6 @@ \section{Fabric Support Attributes}
Total number of fabric devices in the overall system - corresponds to the number of rows or columns in the cost matrix.
}
%
\declareAttributeNEW{PMIX_FABRIC_VIEW}{"pmix.fab.view"}{pmix_coord_view_t}{
Used purely as a qualifier to requests, specifies the view type (e.g., local vs. physical) for the requested information.
}
%
\declareAttributeNEW{PMIX_FABRIC_DIMS}{"pmix.fab.dims"}{uint32_t}{
Number of dimensions in the specified fabric plane/view. If no plane is specified in a request, then the dimensions of all planes in the overall system will be returned as a \refstruct{pmix_data_array_t} containing an array of \code{uint32_t} values. Default is to provide dimensions in \emph{logical} view.
}
Expand Down
Loading