<commit_before>
Guide for HPC Runtime Users
===========================

The GEOPM HPC Runtime package provides many built-in features.  An
advanced use case is dynamically coordinating hardware settings across
all compute nodes used by an distributed HPC application in response
to the application's behavior and resource manager requests.  The
dynamic coordination is implemented as a hierarchical control system
for scalable communication and decentralized control. The hierarchical
control system can optimize for various objective functions including
maximizing global application performance within a power bound or
minimizing energy consumption with marginal degradation of application
performance.  The root of the control hierarchy tree can communicate
with the system resource manager to extend the hierarchy above the
individual MPI application and enable the management of system power
resources for multiple MPI jobs and multiple users by the system
resource manager.

The GEOPM HPC Runtime package provides two libraries: libgeopm for use
with MPI applications, and libgeopmpolicy for use with applications
that do not link to MPI.  There are several command line tools
included in GEOPM which have dedicated manual pages.  The
geopmlaunch(1) command line tool is used to launch an MPI application
while enabling the GEOPM runtime to create a GEOPM Controller thread
on each compute node.  The Controller loads plugins and executes the
Agent algorithm to control the compute application.  The
geopmlaunch(1) command is part of the geopmpy python package that is
included in the GEOPM installation.  See the GEOPM overview man page
for further documentation and links:
`geopm(7) <https://geopm.github.io/man/geopm.7.html>`_.

The GEOPM HPC Runtime provides some built-in algorithms, each as an
"Agent" that implements the geopm::Agent(3) class interface.
A developer may extend these algorithm features by writing an Agent
plugin.  A new implementation of this class can be dynamically loaded
at runtime by the GEOPM Controller.  The Agent class defines which
data are collected, how control decisions are made, and what messages
are communicated between Agents in the tree hierarchy of compute
nodes.  The reading of data and writing of controls from within a
compute node is abstracted from the Agent through the PlatformIO
interface.  The PlatformIO interface is provided by the GEOPM Service
package which is contained in the service directory of the GEOPM
repository.  The PlatformIO abstraction enables Agent implementations
to be ported to different hardware platforms without modification.

The libgeopm library can be called directly or indirectly within MPI
applications to enable application feedback for informing the control
decisions.  The indirect calls are facilitated by GEOPM's integration
with MPI and OpenMP through their profiling decorators, and the direct
calls are made through the geopm_prof_c(3) or geopm_fortran(3)
interfaces.  Marking up a compute application with profiling
information through these interfaces can enable better integration of
the GEOPM runtime with the compute application and more precise
control.

The GEOPM HPC Runtime tutorial shows how to profile unmodified
applications, select and evaluate different GEOPM Agent algorithms,
and how to add markup to an application.  The tutorial provides a good
starting point for someone trying to get familiar witht the GEOPM HPC
Runtime.  The tutorial can be found
`here <https://github.com/geopm/geopm/tree/dev/tutorial>`__.



Build Requirements
------------------

When using the build system in the base of the GEOPM source repository
to build the GEOPM HPC Runtime some additional requirements must be
met.  If the user is not interested in building the GEOPM HPC Runtime,
these extra build requirements may be ignored.  The user may also opt
out of the specific GEOPM HPC Runtime features enabled by any of these
requirements by providing the appropriate disable flag to the base
build configure command line.

The GEOPM HPC runtime requires support for MPI, the Message Passing
Interface, standard 2.2 or higher.  In many cases meeting this
requirement will depend on the specific HPC resource being targeted
based on documentation that is site specific.  The Intel MPI
implementation may be used to meet this requirement.  The MPI
requirement may also be met through HPC packaging systems like OpenHPC
or Spack.  Additionally, the OpenMPI binaries are distributed with
most major Linux distributions, and may also be used to satisfy this
requirement.  This requirement can be met by installing the
``openmpi-devel`` package version 1.7 or greater on RHEL and SLES
Linux, and ``libopenmpi-dev`` on Ubuntu.

* Install all requirements on RHEL or CentOS

  .. code-block:: bash

      yum install openmpi-devel elfutils-libelf-devel


* Install all requirements on SUSE based distributions

  .. code-block:: bash

      zypper install openmpi-devel elfutils-libelf-devel


* Install all requirements on UBUNTU (as of 18.04.3 LTS)

  .. code-block:: bash

      apt install libtool automake libopenmpi-dev build-essential gfortran \
          libelf-dev python libsqlite3-dev


Requirements that can be avoided by removing features with configure
option:

* Remove MPI compiler requirement
  ``--disable-mpi``

* Remove Fortran compiler requirement
  ``--disable-fortran``

* Remove elfutils library requirement
  ``--disable-ompt``


For details on how to use non-standard install locations for build
requirements see

  .. code-block:: bash

    ./configure --help


which describes some options of the form ``--with-<feature>`` that can
be used for this purpose, e.g. ``--with-mpi-bin``.


Building the GEOPM HPC Runtime
------------------------------

The best recommendation for building the GEOPM HPC Runtime is to follow
the developer documentation posted
`here <https://geopm.github.io/geopmpy/devel.html>`__.  This will
enable the use of the GEOPM Service and will also provide the latest
development in the GEOPM repository.


Run Requirements
----------------

The GEOPM HPC Runtime has several requirements at time-of-use beyond
what is required for the GEOPM Service.  These requirements are
outlined here.  A user that is not interested in running the GEOPM HPC
Runtime may ignore these requirements.


MPI Requirements
^^^^^^^^^^^^^^^^

Using the GEOPM HPC Runtime requires that the package was built
against the same MPI implementation that is used at runtime to launch
the user's application.


BIOS Configuration<commit_msg>Fix dead link in runtime.html<commit_after>
Guide for HPC Runtime Users
===========================

The GEOPM HPC Runtime package provides many built-in features.  An
advanced use case is dynamically coordinating hardware settings across
all compute nodes used by an distributed HPC application in response
to the application's behavior and resource manager requests.  The
dynamic coordination is implemented as a hierarchical control system
for scalable communication and decentralized control. The hierarchical
control system can optimize for various objective functions including
maximizing global application performance within a power bound or
minimizing energy consumption with marginal degradation of application
performance.  The root of the control hierarchy tree can communicate
with the system resource manager to extend the hierarchy above the
individual MPI application and enable the management of system power
resources for multiple MPI jobs and multiple users by the system
resource manager.

The GEOPM HPC Runtime package provides two libraries: libgeopm for use
with MPI applications, and libgeopmpolicy for use with applications
that do not link to MPI.  There are several command line tools
included in GEOPM which have dedicated manual pages.  The
geopmlaunch(1) command line tool is used to launch an MPI application
while enabling the GEOPM runtime to create a GEOPM Controller thread
on each compute node.  The Controller loads plugins and executes the
Agent algorithm to control the compute application.  The
geopmlaunch(1) command is part of the geopmpy python package that is
included in the GEOPM installation.  See the GEOPM overview man page
for further documentation and links:
`geopm(7) <https://geopm.github.io/man/geopm.7.html>`_.

The GEOPM HPC Runtime provides some built-in algorithms, each as an
"Agent" that implements the geopm::Agent(3) class interface.
A developer may extend these algorithm features by writing an Agent
plugin.  A new implementation of this class can be dynamically loaded
at runtime by the GEOPM Controller.  The Agent class defines which
data are collected, how control decisions are made, and what messages
are communicated between Agents in the tree hierarchy of compute
nodes.  The reading of data and writing of controls from within a
compute node is abstracted from the Agent through the PlatformIO
interface.  The PlatformIO interface is provided by the GEOPM Service
package which is contained in the service directory of the GEOPM
repository.  The PlatformIO abstraction enables Agent implementations
to be ported to different hardware platforms without modification.

The libgeopm library can be called directly or indirectly within MPI
applications to enable application feedback for informing the control
decisions.  The indirect calls are facilitated by GEOPM's integration
with MPI and OpenMP through their profiling decorators, and the direct
calls are made through the geopm_prof_c(3) or geopm_fortran(3)
interfaces.  Marking up a compute application with profiling
information through these interfaces can enable better integration of
the GEOPM runtime with the compute application and more precise
control.

The GEOPM HPC Runtime tutorial shows how to profile unmodified
applications, select and evaluate different GEOPM Agent algorithms,
and how to add markup to an application.  The tutorial provides a good
starting point for someone trying to get familiar witht the GEOPM HPC
Runtime.  The tutorial can be found
`here <https://github.com/geopm/geopm/tree/dev/tutorial>`__.



Build Requirements
------------------

When using the build system in the base of the GEOPM source repository
to build the GEOPM HPC Runtime some additional requirements must be
met.  If the user is not interested in building the GEOPM HPC Runtime,
these extra build requirements may be ignored.  The user may also opt
out of the specific GEOPM HPC Runtime features enabled by any of these
requirements by providing the appropriate disable flag to the base
build configure command line.

The GEOPM HPC runtime requires support for MPI, the Message Passing
Interface, standard 2.2 or higher.  In many cases meeting this
requirement will depend on the specific HPC resource being targeted
based on documentation that is site specific.  The Intel MPI
implementation may be used to meet this requirement.  The MPI
requirement may also be met through HPC packaging systems like OpenHPC
or Spack.  Additionally, the OpenMPI binaries are distributed with
most major Linux distributions, and may also be used to satisfy this
requirement.  This requirement can be met by installing the
``openmpi-devel`` package version 1.7 or greater on RHEL and SLES
Linux, and ``libopenmpi-dev`` on Ubuntu.

* Install all requirements on RHEL or CentOS

  .. code-block:: bash

      yum install openmpi-devel elfutils-libelf-devel


* Install all requirements on SUSE based distributions

  .. code-block:: bash

      zypper install openmpi-devel elfutils-libelf-devel


* Install all requirements on UBUNTU (as of 18.04.3 LTS)

  .. code-block:: bash

      apt install libtool automake libopenmpi-dev build-essential gfortran \
          libelf-dev python libsqlite3-dev


Requirements that can be avoided by removing features with configure
option:

* Remove MPI compiler requirement
  ``--disable-mpi``

* Remove Fortran compiler requirement
  ``--disable-fortran``

* Remove elfutils library requirement
  ``--disable-ompt``


For details on how to use non-standard install locations for build
requirements see

  .. code-block:: bash

    ./configure --help


which describes some options of the form ``--with-<feature>`` that can
be used for this purpose, e.g. ``--with-mpi-bin``.


Building the GEOPM HPC Runtime
------------------------------

The best recommendation for building the GEOPM HPC Runtime is to follow
the developer documentation posted
`here <devel.html>`__.  This will
enable the use of the GEOPM Service and will also provide the latest
development in the GEOPM repository.


Run Requirements
----------------

The GEOPM HPC Runtime has several requirements at time-of-use beyond
what is required for the GEOPM Service.  These requirements are
outlined here.  A user that is not interested in running the GEOPM HPC
Runtime may ignore these requirements.


MPI Requirements
^^^^^^^^^^^^^^^^

Using the GEOPM HPC Runtime requires that the package was built
against the same MPI implementation that is used at runtime to launch
the user's application.


BIOS Configuration
{'fraction_non_alphanumeric': 0.04937328034240294, 'fraction_numerical': 0.0025985937022317334, 'mean_word_length': 4.362704918032787, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 5, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5693928', 'n_tokens_mistral': 3352, 'n_tokens_neox': 3065, 'n_words': 1815}