First commit

.gitignore

@@ -0,0 +1 @@
+build

CMakeLists.txt

@@ -0,0 +1,91 @@
+# Copyright 2020 Lawrence Livermore National Security, LLC and other CLIPPy
+# Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: MIT
+
+# Works with 3.11 and tested through 3.15 (not tested yet)
+cmake_minimum_required(VERSION 3.11...3.15)
+
+project(CLIPPy
+    VERSION 0.1
+    DESCRIPTION "Command Line Interface Plus Python"
+    LANGUAGES CXX)
+
+# Only do these if this is the main project, and not if it is included through add_subdirectory
+if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+
+    set(CMAKE_CXX_STANDARD 17)
+    set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+    # Let's ensure -std=c++xx instead of -std=g++xx
+    set(CMAKE_CXX_EXTENSIONS OFF)
+
+    # Let's nicely support folders in IDE's
+    set_property(GLOBAL PROPERTY USE_FOLDERS ON)
+
+    # Testing only available if this is the main app
+    # Note this needs to be done in the main CMakeLists
+    # since it calls enable_testing, which must be in the
+    # main CMakeLists.
+    include(CTest)
+
+    # Docs only available if this is the main app
+    find_package(Doxygen)
+    if(Doxygen_FOUND)
+	#add_subdirectory(docs)
+    else()
+	message(STATUS "Doxygen not found, not building docs")
+    endif()
+endif()
+
+
+#
+#  Nlohmann JSON
+#
+include(ExternalProject)
+ExternalProject_Add(nlohmann_json
+    URL https://github.com/nlohmann/json/releases/download/v3.9.1/json.hpp
+    DOWNLOAD_NO_EXTRACT 1
+    LOG_DOWNLOAD 1
+    DOWNLOAD_DIR nlohmann_json/include/nlohmann/
+    BUILD_COMMAND ""
+    INSTALL_COMMAND ""
+    CONFIGURE_COMMAND ""
+    )
+set(NLOHMANN_JSON_INCLUDE_DIR ${PROJECT_BINARY_DIR}/nlohmann_json/include)
+
+#
+#  Metall
+#
+ExternalProject_Add(metall
+    GIT_REPOSITORY https://github.com/LLNL/metall.git
+    GIT_TAG v0.5
+    CONFIGURE_COMMAND ""
+    GIT_PROGRESS 1
+    BUILD_COMMAND ""
+    INSTALL_COMMAND ""
+    #LOG_DOWNLOAD 1
+    )
+ExternalProject_Get_Property(metall source_dir)
+set(METALL_INCLUDE_DIR ${source_dir}/include)
+
+### Require out-of-source builds
+file(TO_CMAKE_PATH "${PROJECT_BINARY_DIR}/CMakeLists.txt" LOC_PATH)
+if(EXISTS "${LOC_PATH}")
+    message(FATAL_ERROR "You cannot build in a source directory (or any directory with a CMakeLists.txt file). Please make a build subdirectory. Feel free to remove CMakeCache.txt and CMakeFiles.")
+endif()
+
+include_directories("${PROJECT_SOURCE_DIR}/include")
+
+option(TEST_WITH_SLURM "Run tests with Slurm" OFF)
+
+# Header-only library, so likely not have src dir 
+# add_subdirectory(src)
+
+# Testing & examples are only available if this is the main app
+# Emergency override MODERN_CMAKE_BUILD_TESTING provided as well
+if((CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME OR MODERN_CMAKE_BUILD_TESTING) AND BUILD_TESTING)
+    #add_subdirectory(test)
+    # Example codes are here.
+    add_subdirectory(examples)
+endif()

COPYRIGHT

@@ -0,0 +1,19 @@
+Intellectual Property Notice
+------------------------------
+
+CLIPPy uses the MIT license, (LICENSE-MIT or http://opensource.org/licenses/MIT).
+
+Copyrights and patents in the CLIPPy project are retained by contributors.
+No copyright assignment is required to contribute to CLIPPy.
+
+
+SPDX usage
+------------
+
+Individual files contain SPDX tags instead of the full license text.
+This enables machine processing of license information based on the SPDX
+License Identifiers that are available here: https://spdx.org/licenses/
+
+Files that MIT contain the following text in the license header:
+
+    SPDX-License-Identifier: MIT

NOTICE

@@ -0,0 +1,21 @@
+This work was produced under the auspices of the U.S. Department of
+Energy by Lawrence Livermore National Laboratory under Contract
+DE-AC52-07NA27344.
+
+This work was prepared as an account of work sponsored by an agency of
+the United States Government. Neither the United States Government nor
+Lawrence Livermore National Security, LLC, nor any of their employees
+makes any warranty, expressed or implied, or assumes any legal liability
+or responsibility for the accuracy, completeness, or usefulness of any
+information, apparatus, product, or process disclosed, or represents that
+its use would not infringe privately owned rights.
+
+Reference herein to any specific commercial product, process, or service
+by trade name, trademark, manufacturer, or otherwise does not necessarily
+constitute or imply its endorsement, recommendation, or favoring by the
+United States Government or Lawrence Livermore National Security, LLC.
+
+The views and opinions of authors expressed herein do not necessarily
+state or reflect those of the United States Government or Lawrence
+Livermore National Security, LLC, and shall not be used for advertising
+or product endorsement purposes.

README.md

@@ -0,0 +1,137 @@
+# CLIPPy - Command Line Interface Plus Python
+ ````
+ ╭────────────────────────────────────╮
+ │ It looks like you want to use HPC. │ 
+ │ Would you like help with that?     │
+ ╰────────────────────────────────────╯
+  ╲
+   ╲
+    ╭──╮  
+    ⊙ ⊙│╭
+    ││ ││
+    │╰─╯│
+    ╰───╯
+````
+
+## Overview
+
+Clippy (CLI + PYthon) is a Python language interface to HPC resources. Precompiled binaries
+that execute on HPC systems are exposed as methods to a dynamically-created `Clippy` Python
+object, where they present a familiar interface to researchers, data scientists, and others.
+Clippy allows these users to interact with HPC resources in an easy, straightforward
+environment – at the REPL, for example, or within a notebook – without the need to learn
+complex HPC behavior and arcane job submission commands.
+
+This repository contains the C++ libraries necessary to interface with the Clippy python interface.
+
+
+## Building C++ Examples  on LC
+
+```console
+$ . /usr/workspace/llamag/spack/share/spack/setup-env.sh
+$ spack load gcc
+$ spack load boost
+$ mkdir build
+$ cd build
+$ cmake ../
+$ make
+$ cd ../.. #back to root project directory 
+```
+
+## Running Current Examples
+```python
+$ ipython3-3.8.2
+
+In [1]: from clippy import Clippy
+
+ ╭────────────────────────────────────╮
+ │ It looks like you want to use HPC. │ 
+ │ Would you like help with that?     │
+ ╰────────────────────────────────────╯
+  ╲
+   ╲
+    ╭──╮  
+    ⊙ ⊙│╭
+    ││ ││
+    │╰─╯│
+    ╰───╯
+
+In [2]: c = Clippy({'examples': 'clippy/cpp/build/examples'}, cmd_prefix='', loglevel=0)
+
+In [3]: c.examples.howdy('Seth')  # can also use a named arg: c.examples.howdy(name='Seth')
+Out[3]: 'Howdy, Seth!'
+
+In [4]: c.examples.sum(1, 2)
+Out[4]: 3.0
+
+In [5]: c.examples.sort_edges([(5,5),(3,5),(2,2),(0,0)])
+Out[5]: [[0, 0], [2, 2], [3, 5], [5, 5]]
+
+In [6]: c.examples.sort_edges([(5,5),(3,5),(2,2),(0,0)], reverse=True)
+Out[6]: [[5, 5], [3, 5], [2, 2], [0, 0]]
+
+In [7]: c.examples.sort_strings(['zulu','yankee','whiskey','uniform','romeo','mike','kilo','foxtrot','delta','alfa'])
+Out[7]: 
+['alfa',
+ 'delta',
+ 'foxtrot',
+ 'kilo',
+ 'mike',
+ 'romeo',
+ 'uniform',
+ 'whiskey',
+ 'yankee',
+ 'zulu']
+
+In [8]: c.examples.sort_strings(['zulu','yankee','whiskey','uniform','romeo','mike','kilo','foxtrot','delta','alfa'], reverse=True)
+Out[8]: 
+['zulu',
+ 'yankee',
+ 'whiskey',
+ 'uniform',
+ 'romeo',
+ 'mike',
+ 'kilo',
+ 'foxtrot',
+ 'delta',
+ 'alfa']
+
+In [9]: c.examples.grumpy()
+---------------------------------------------------------------------------
+ClippyBackendError                        Traceback (most recent call last)
+<ipython-input-8-bf61ad375b31> in <module>
+----> 1 c.grumpy()
+
+~/clippy/clippy.py in fn(self, *args, **kwargs)
+    125             #
+    126             # send_dict['args'] = kwargs
+--> 127             j = capself.session.exec(capself.name, kwargs)
+    128             return j
+    129 
+
+~/clippy/clippy.py in exec(self, cmd, submission_dict)
+    196         self.logger.debug(f'run(): result = {p}')
+    197         if p.returncode != 0:
+--> 198             raise ClippyBackendError(p.stderr)
+    199 
+    200         return json.loads(p.stdout)
+
+ClippyBackendError: terminate called after throwing an instance of 'std::runtime_error'
+  what():  I'm Grumpy!
+```
+
+## Authors
+- Seth Bromberger (seth at llnl dot gov)
+- Roger Pearce (rpearce at llnl dot gov)
+
+
+## License
+CLIPPy is distributed under the MIT license.
+
+See [LICENSE-MIT](LICENSE-MIT), [NOTICE](NOTICE), and [COPYRIGHT](COPYRIGHT) for
+details.
+
+SPDX-License-Identifier: MIT
+
+## Release
+LLNL-CODE-818157

examples/CMakeLists.txt

@@ -0,0 +1,28 @@
+# Copyright 2020 Lawrence Livermore National Security, LLC and other CLIPPy
+# Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: MIT
+
+#
+# This function adds an mpi example.
+#
+function ( add_example example_name )
+  set(example_source "${example_name}.cpp")
+  set(example_exe    "${example_name}")
+  add_executable(${example_exe} ${example_source})
+  target_include_directories(${example_exe} PRIVATE ${METALL_INCLUDE_DIR})
+  target_include_directories(${example_exe} PRIVATE ${NLOHMANN_JSON_INCLUDE_DIR})
+  add_dependencies(${example_exe} metall)
+  add_dependencies(${example_exe} nlohmann_json)
+  if(UNIX AND NOT APPLE)
+    target_link_libraries(${example_exe} rt)
+  endif()
+  include_directories(${CMAKE_CURRENT_SOURCE_DIR})
+endfunction()
+
+add_example(grumpy)
+add_example(sort_edges)
+add_example(sort_strings)
+add_example(howdy)
+add_example(sum)
+add_example(return_tuple)

examples/README.md

@@ -0,0 +1,20 @@
+# C++ Examples using CLIPPy
+This directory contains a series of examples of using CLIPPy for command
+line configuration.   
+
+
+**NOTE:** These examples are trivial and are used for illustration and testing 
+purposes.  In no way are we advocating sorting strings externally to 
+Python, for example.
+
+
+## Examples
+
+- [howdy.cpp](howdy.cpp):  Example of String input and output
+- [sum.cpp](sum.cpp): Example of Number input and output
+- [sort_edges.cpp](sort_edges.cpp): Example of VectorIntInt input and output, also contains optional Boolean.
+- [sort_strings.cpp](sort_strings.cpp): Example of VectorStrings input and output, also contains optional Boolean.
+- [grumpy.cpp](grumpy.cpp): Example of exception throwing in C++ backend.  Grumpy always throws a std::runtime_error()
+
+## Building
+Edit the `Makefile` as necessary and run `make`.

examples/grumpy.cpp

@@ -0,0 +1,18 @@
+// Copyright 2019 Lawrence Livermore National Security, LLC and other Clippy Project Developers.
+// See the top-level COPYRIGHT file for details.
+//
+// SPDX-License-Identifier: MIT
+
+#include <clippy/clippy.hpp>
+
+int main(int argc, char **argv)
+{
+  clippy::clippy clip("grumpy", "Always throws errors because he's Grumpy!");
+  if (clip.parse(argc, argv))
+  {
+    return 0;
+  }
+
+  throw std::runtime_error("I'm Grumpy!");
+  return 0;
+}

examples/howdy.cpp

@@ -0,0 +1,18 @@
+// Copyright 2020 Lawrence Livermore National Security, LLC and other CLIPPy Project Developers.
+// See the top-level COPYRIGHT file for details.
+//
+// SPDX-License-Identifier: MIT
+
+#include <clippy/clippy.hpp>
+
+int main(int argc, char **argv) {
+  clippy::clippy clip("howdy", "Formal Texan greeting.");
+  clip.add_required<clippy::string>("name", "Name to greet");
+  clip.returns<clippy::string>("The greeting");
+  if (clip.parse(argc, argv)) { return 0; }
+
+  auto name = clip.get<clippy::string>("name");
+
+  clip.to_return(std::string("Howdy, ") + name);
+  return 0;
+}

examples/return_tuple.cpp

@@ -0,0 +1,18 @@
+// Copyright 2020 Lawrence Livermore National Security, LLC and other CLIPPy Project Developers.
+// See the top-level COPYRIGHT file for details.
+//
+// SPDX-License-Identifier: MIT
+
+#include <tuple>
+#include <clippy/clippy.hpp>
+#include <typeinfo>
+
+int main(int argc, char **argv) {
+  clippy::clippy clip("return_tuple", "Always returns a tuple");
+
+  if (clip.parse(argc, argv)) { return 0; }
+
+  clip.to_return(std::make_tuple("foo", 42, 3.24));
+
+  return 0;
+}