<img src="https://geopm.github.io/images/geopm-banner.png" alt="GEOPM logo">

# GEOPM - Global Extensible Open Power Manager

[![Build Status](https://github.com/geopm/geopm/actions/workflows/build.yml/badge.svg)](https://github.com/geopm/geopm/actions)
[![version](https://img.shields.io/badge/version-2.0.0-blue)](https://github.com/geopm/geopm/releases)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)


## Web Pages

https://geopm.github.io <br>
https://geopm.github.io/service.html <br>
https://geopm.github.io/reference.html <br>
https://geopm.slack.com <br>
https://build.opensuse.org/package/show/hardware/geopm-service


## Summary

The Global Extensible Open Power Manager (GEOPM) is a framework for
exploring power and energy optimizations on heterogeneous platforms.

With GEOPM you can:

- Interact with hardware settings and sensors using a
  platform-agnostic interface
- Restore changes to hardware settings when configuring process
  session terminates
- Profile applications to study their power and energy behavior
- Optimize applications to improve energy efficiency or reduce the
  effects of work imbalance, system jitter, and manufacturing variation
  through built-in control algorithms
- Automatically detect MPI and OpenMP phases in an application
- Develop your own runtime control algorithms through the extensible
  plugin architecture


## Repository Organization

The GEOPM repository supports two software packages: the
`geopm-service` package and the `geopm-runtime` package.

- A build of the `geopm-service` package is required to build and run
  the `geopm-runtime`

- All `geopm-service` package features may be used independently of
  the features provided by the `geopm-runtime` package


## GEOPM Service

GEOPM provides Hardware Configuration as a Service (HCaaS) with a high
level interface to interact with low level hardware features.  This
service abstracts vendor specific information, provides security and
quality of service guarantees while executing with very high
performance and low overhead.

The files supporting the `geopm-service` package are all within the
`service` sub-directory located in the root directory of the the GEOPM
repository.  Please refer to the [service README](service/README.rst)
file for further documentation about the GEOPM Service.  Additionally,
an overview of the GEOPM service is posted in our [online
documentation](https://geopm.github.io/service.html).


## GEOPM Runtime

GEOPM's Hardware Tuning Runtime adjusts hardware settings achieve an
energy efficiency goal in response to hardware metrics and application
telemetry.  The control system can optimize for user controlled
objective functions including maximizing global application
performance within a power bound or minimizing energy consumption with
marginal degradation of application performance.

An overview of the GEOPM Runtime is posted in our [online
documentation](https://geopm.github.io/runtime.html)


## Guide for Contributors

We appreciate all feedback on our project.  Please see our
contributing guide for how some guidelines on how to participate.
This guide is located in the root of the GEOPM repository in a file
called [CONTRIBUTING.rst](CONTRIBUTING.rst).  This guide can also be viewed in our
[online documentation](https://geopm.github.io/contrib.html).


## Guide for GEOPM Developers

GEOPM is an open development project and we use Github to plan, review
and test our work.  The process we follow is documented in our [online
documentation](https://geopm.github.io/devel.html).  This web page
provides a guide for developers wishing to modify source code anywhere
in the GEOPM repository for both the `geopm-service` and the `geopm`
packages.


## Experimental Branch

This version of GEOPM is currently posted on the ``cloud`` branch and
represents a proof of concept for applying GEOPM to cloud
applications.  The features under development in this branch will be
merged into the main ``dev`` branch when they are production quality,
and eventually the ``cloud`` branch will be deleted.

This version of GEOPM is experimental and should not be used as a
production tool.

### New Features

- Runtime support for non-MPI applications
  + Feature issue https://github.com/geopm/geopm/issues/2875
  + Pull request https://github.com/geopm/geopm/pull/2836
  + Status: Unstable version in cloud branch
- Runtime support for non-MPI node-local controller
  + Implemented as part of https://github.com/geopm/geopm/pull/2836
  + Status: Unstable version in cloud branch
- Option to use gRPC in place of DBus communication
  + Feature issue https://github.com/geopm/geopm/issues/2775
  + Pull request https://github.com/geopm/geopm/pull/2779
  + Status: Merged into cloud branch, but integration tests are failing:
    python gRPC server hangs and never creates either Unix domain socket.
    This is a regression introduced into the cloud branch since the feature
    was first implemented. This seems to be related to an upstream issue with
    gRPC: https://github.com/grpc/grpc/issues/31885
- Rust front-end proxy server for gRPC API
  + Implemented as part of https://github.com/geopm/geopm/pull/2779
  + Status: See above, gRPC integration tests are failing, but not root caused
- Support for liburing for asynchronous kernel IO
  + Feature issue https://github.com/geopm/geopm/issues/2781
  + Pull request https://github.com/geopm/geopm/pull/2782
  + Status: Considered stable, but not merged to the dev branch yet
- Kubernetes examples for using the service and the runtime
  + Topic does not currently have supporting Github issues or pull requests
  + The cloud branch contains [a service example](service/README.rst#kubernetes-support)
    and [a runtime example](k8/k8-monitor.yaml)
- Docker files for creating service and client containers
  + Topic does not currently have supporting Github issues or pull requests
  + The cloud branch provides [a GEOPM Service Dockerfile](service/Dockerfile)
    and several examples in the [k8](k8) directory for client and service
    docker containers.
- Packaging for Ubuntu
  + Topic does not currently have supporting Github issues or pull requests
  + The cloud branch provides debian packaging for the GEOPM Service and the
    GEOPM Runtime.
- Improvements in platform topology consistency
  + Issue https://github.com/geopm/geopm/issues/2832
  + Pull request https://github.com/geopm/geopm/pull/2845
  + Feature was in the cloud branch, but has been partially reverted due to
    regressions
  + Some gRPC features added to support passing the platform topology are
    still in the cloud branch and may be related to issues in the gRPC support
    in the cloud branch
- User controlled loop period
  + Feature issue https://github.com/geopm/geopm/issues/1065
  + Pull request https://github.com/geopm/geopm/pull/2867
  + Feature is merged into cloud branch
  + Status: needs clean up (better handling of invalid input and unit tests)
    but otherwise appears functional


The GEOPM developers are very interested in feedback from the
community.  See the [contributing guide](CONTRIBUTING.md) to learn how
to provide feedback.


License
-------

The GEOPM source code is distributed under the 3-clause BSD license.

SEE COPYING FILE FOR LICENSE INFORMATION.


Last Update
-----------
2023 March 2

Christopher Cantalupo <christopher.m.cantalupo@intel.com> <br>
Brad Geltz <brad.geltz@intel.com> <br>


ACKNOWLEDGMENTS
---------------
Development of the GEOPM software package has been partially funded
through contract B609815 with Argonne National Laboratory.
