Merge branch 'release/0.4.0'

.github/workflows/build.yml → .github/workflows/build-develop.yml

@@ -1,10 +1,10 @@
-name: Build
+name: Build (develop)
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ develop ]
   pull_request:
-    branches: [ main, develop ]
+    branches: [ develop ]
 
 env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)

.github/workflows/build-main.yml

@@ -0,0 +1,51 @@
+name: Build (main)
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
+  BUILD_TYPE: Debug
+
+jobs:
+  build:
+    # The CMake configure and build commands are platform agnostic and should work equally
+    # well on Windows or Mac.  You can convert this to a matrix build if you need
+    # cross-platform coverage.
+    # See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Install Conan
+      id: conan
+      uses: turtlebrowser/get-conan@main
+
+    - name: Conan The Frogarian
+      run: conan frogarian
+
+    - name: Conan Profile Setup
+      run: |
+        conan config init
+        conan profile update settings.compiler.libcxx=libstdc++11 default
+
+    - name: Conan Install Dependencies
+      run: conan install -if build . 
+
+    - name: Configure CMake
+      # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
+      # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
+      run: cmake -B build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
+
+    - name: Build
+      # Build your program with the given configuration
+      run: cmake --build build --config ${{env.BUILD_TYPE}}
+
+    - name: Test
+      # Execute tests defined by the CMake configuration.  
+      # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
+      run: cmake --build build --target test --config ${{env.BUILD_TYPE}}

CMakeLists.txt

@@ -28,8 +28,8 @@
 cmake_minimum_required(VERSION 3.13) # GENERATOR_IS_MULTI_CONFIG
 
 set(KAMI_VERSION_MAJOR 0)
-set(KAMI_VERSION_MINOR 3)
-set(KAMI_VERSION_PATCH 1)
+set(KAMI_VERSION_MINOR 4)
+set(KAMI_VERSION_PATCH 0)
 set(KAMI_VERSION_STRING ${KAMI_VERSION_MAJOR}.${KAMI_VERSION_MINOR}.${KAMI_VERSION_PATCH})
 
 ################################################################################

README.md

@@ -1,8 +1,7 @@
 [![Build status (main)](https://github.com/JHUAPL/kami/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/JHUAPL/kami/actions/workflows/build.yml)
 [![Build status (develop)](https://github.com/JHUAPL/kami/actions/workflows/build.yml/badge.svg?branch=develop)](https://github.com/JHUAPL/kami/actions/workflows/build.yml)
 [![Documentation status](https://readthedocs.org/projects/kami/badge/?version=latest)](https://kami.readthedocs.io/en/latest/?badge=latest)
-[![Release status](https://img.shields.io/github/release/JHUAPL/kami.svg)](https://github.com/JHUAPL/kami/releases/latest)
-[![ConanCenter status](https://repology.org/badge/version-for-repo/conancenter/kami.svg)](https://repology.org/project/kami/versions)
+![License](https://img.shields.io/github/license/JHUAPL/kami)
 
 # Kami is Agent-Based Modeling in Modern C++
 

conanfile.py

@@ -3,7 +3,7 @@
 
 class KamiConan(ConanFile):
     name = "kami"
-    version = "0.3.1"
+    version = "0.4.0"
     license = "MIT"
     author = "James P. Howard, II <[email protected]>"
     url = "http://github.com/jhuapl/kami"

docs/changelog.rst

@@ -0,0 +1,14 @@
+Changelog
+=========
+
+- :bug:`0` Cleaned up numerous issues found by CLion's linter
+- :feature:`0` Added a new overview to the documents
+- :feature:`0` Added basic installation instructions
+- :bug:`0` Retagged previous versions using pure Semantic Versioning
+- :feature:`0` Documentation for `kami::RandomScheduler`
+- :feature:`0` Added a changelog!
+
+- :release:`0.3.0 <2021.09.20>`
+- :feature:`0` Initial public release.
+
+..  toctree::

docs/conf.py

@@ -43,7 +43,11 @@ def configureDoxyfile(input_dir, output_dir):
     'sphinx.ext.githubpages',
     'breathe',
     'exhale',
-    'myst_parser']
+    'myst_parser',
+    'releases']
+
+# 'releases' (changelog) settings
+releases_github_path = "JHUAPL/kami"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/index.rst

@@ -1,34 +1,30 @@
 Introduction
 ============
 
-..  |Build (main)| image:: https://github.com/JHUAPL/kami/actions/workflows/build.yml/badge.svg?branch=main
-    :target: https://github.com/JHUAPL/kami/actions/workflows/build.yml
-..  |Build (develop)| image:: https://github.com/JHUAPL/kami/actions/workflows/build.yml/badge.svg?branch=develop
-    :target: https://github.com/JHUAPL/kami/actions/workflows/build.yml
-    :alt: Build status (develop)
-..  |Documentation Status| image:: https://readthedocs.org/projects/kami/badge/?version=latest
+..  image:: https://github.com/JHUAPL/kami/actions/workflows/build-main.yml/badge.svg?branch=main
+    :target: https://github.com/JHUAPL/kami/actions/workflows/build-main.yml
+    :alt: Build Status (main)
+..  image:: https://github.com/JHUAPL/kami/actions/workflows/build-develop.yml/badge.svg?branch=develop
+    :target: https://github.com/JHUAPL/kami/actions/workflows/build-develop.yml
+    :alt: Build Status (develop)
+..  image:: https://readthedocs.org/projects/kami/badge/?version=latest
     :target: https://kami.readthedocs.io/en/latest/?badge=latest
-    :alt: Documentation status
-..  |Release| image:: https://img.shields.io/github/release/JHUAPL/kami.svg
-    :target: https://github.com/JHUAPL/spdlog/kami/latest
-    :alt: Release status
-..  |ConanCenter package| image:: https://repology.org/badge/version-for-repo/conancenter/kami.svg
-    :target: https://repology.org/project/kami/versions
-    :alt: ConanCenter status
+    :alt: Documentation Status
+..  image:: https://img.shields.io/github/release/JHUAPL/kami.svg
+    :target: https://github.com/JHUAPL/kami/releases
+    :alt: Release Status
+..  image:: https://img.shields.io/github/license/JHUAPL/kami
+    :alt: License Information
 
-Kami is agent-based modeling modern C++.  The objectives in writing
-Kami are that it be lightweight, memory-efficient, and fast.  It
-should be possible to develop a simple working model in under one
-hour of C++ development time.  Accordingly, the platform is modeled
-extensively on the `Mesa
-<https://mesa.readthedocs.io/en/stable/overview.html>`_ library in
-Python, which itself was inspired by the `MASON
-<https://cs.gmu.edu/~eclab/projects/mason/>`_ library in Java.
+Kami is Agent-Based Modeling in Modern C++.
 
-.. toctree::
-   :maxdepth: 2
-   :hidden:
+..  toctree::
+    :hidden:
+    :maxdepth: 2
 
-   tutorial
-   api/library_root
-   license
+    overview
+    installation
+    tutorial
+    api/library_root
+    changelog
+    license

docs/installation.md

@@ -0,0 +1,35 @@
+# Installation
+
+## Requirements
+
+The core of Kami, `libkami`, has no requirements beyond a modern C++ compiler. However, both the examples provided and
+the unit tests provided rely on three additional C++ packages:
+
+* cli11/1.9.1
+* spdlog/1.8.5
+* fmt/7.1.3
+
+[`CLI11`](https://cliutils.github.io/CLI11/) provides a command line interface for each of the utilities that makeup the
+examples and test suite.  [`spdlog`](https://github.com/gabime/spdlog)
+provides a uniform output interface. Coupled with a command line option to set the output level, `spdlog` allows the
+unit tests and example programs to provide variable output levels depending on the users needs.
+Finally, [`fmt`](https://fmt.dev/) is required by
+`spdlog` for simple and easy string formatting.
+
+## Compiling
+
+To compile and test locally in kami/build:
+
+    git clone https://github.com/k3jph/kami.git
+    cd kami
+    conan install -if build .
+    cmake -B build -DBUILD_SHARED_LIBS:BOOL=FALSE
+    cmake --build build
+    cmake --build build --target test
+
+## Conan Installation (Local)
+
+To install via [Conan](https://conan.io/):
+
+    conan create . kami/develop
+

docs/license.rst

@@ -22,4 +22,6 @@ NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
 BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.
+
+..  toctree::

docs/overview.rst

@@ -0,0 +1,37 @@
+Overview
+========
+
+Agent-based models (ABMs) are models for simulating the actions of
+individual actors within a provided environment to understand the
+behavior of the agents, most individually and collectively.  ABMs
+are particularly suited for addressing problems governed by nonlinear
+processes or where there is a wide variety of potential responses
+an individual agent may provide depending on the environment and
+behavior of other agents.  Because of this, ABMs have become powerful
+tools in both simulation and modeling, especially in public health
+and ecology, where they are also known as individual-based models.
+ABMs also provide support in economic, business, robotics, and many
+other fields.
+
+Design Objectives
+-----------------
+
+Kami provides agent-based modeling modern C++.  The objectives in
+writing Kami are that it be lightweight, memory-efficient, and fast.
+It should be possible to develop a simple working model in under
+one hour of C++ development time.  Accordingly, the platform is
+modeled on the Mesa_ library in Python, which itself was inspired
+by the MASON_ library in Java.
+
+Many ABM platforms are designed around interaction and real time
+observation of the agent dynamics.  Kami does not provide a
+visualization interface.  Instead, Kami is meant to be used for
+ABMs requiring many runs with different starting conditions.
+Accordingly, Kami is single-threaded and multiple cores should be
+taken advantage of through multiple parallel runs of the supervising
+model.
+
+..  _MASON: https://cs.gmu.edu/~eclab/projects/mason/
+..  _Mesa: https://mesa.readthedocs.io
+
+..  toctree::

docs/requirements.txt

@@ -4,3 +4,5 @@ exhale
 documenteer
 myst-parser
 sphinx_bootstrap_theme
+sphinx_rtd_theme
+releases