Merge branch 'release/0.7.0'

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,89 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main", "develop" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "main", "develop" ]
+  schedule:
+    - cron: '38 4 * * 1'
+
+env:
+  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
+  BUILD_TYPE: Debug
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'cpp' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+
+          # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+          # queries: security-extended,security-and-quality
+
+      - 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 . --build=missing
+
+      - 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}}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

CITATION.cff

@@ -0,0 +1,25 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: Kami is Agent-Based Modeling in Modern C++
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+license: MIT
+repository-code: "https://github.com/JHUAPL/kami"
+authors:
+  - given-names: James Patrick
+    family-names: Howard
+    name-suffix: II
+    email: james.howard@jhu.edu
+    affiliation: Johns Hopkins Applied Physics Laboratory
+    orcid: 'https://orcid.org/0000-0003-4530-1547'
+keywords:
+  - "agent-based modelling"
+  - research
+identifiers:
+  - description: "This is the collection of archived snapshots of all versions of Kami"
+    type: doi
+    value: 10.5281/zenodo.6975259

CMakeLists.txt

@@ -5,7 +5,7 @@ cmake_minimum_required(VERSION 3.13)
 set(PROJECT_NAME "kami")
 
 set(VERSION_MAJOR 0)
-set(VERSION_MINOR 6)
+set(VERSION_MINOR 7)
 set(VERSION_PATCH 0)
 set(VERSION_STRING ${VERSION_MAJOR}.${VERSION_MINOR}.${VERSION_PATCH})
 

COPYRIGHT

@@ -1,4 +1,4 @@
-Copyright (c) 2020-2022 The Johns Hopkins University Applied Physics
+Copyright (c) 2020-2023 The Johns Hopkins University Applied Physics
 Laboratory LLC
 
 Permission is hereby granted, free of charge, to any person

README.md

@@ -3,6 +3,7 @@
 [![Documentation status](https://readthedocs.org/projects/kami/badge/?version=main)](https://kami.readthedocs.io/en/main/)
 [![Release status](https://img.shields.io/github/release/JHUAPL/kami.svg)](https://github.com/JHUAPL/kami/releases)
 ![License](https://img.shields.io/github/license/JHUAPL/kami)
+[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.6975259-success.svg)](https://doi.org/10.5281/zenodo.6975259)
 
 # Kami is Agent-Based Modeling in Modern C++
 

conanfile.py

@@ -3,7 +3,7 @@
 
 class KamiConan(ConanFile):
     name = "kami"
-    version = "0.6.0"
+    version = "0.7.0"
     license = "MIT"
     author = "James P. Howard, II <james.howard@jhu.edu>"
     url = "https://github.com/jhuapl/kami"
@@ -49,3 +49,4 @@ def requirements(self):
         self.requires("cli11/2.2.0")
         self.requires("neargye-semver/0.3.0")
         self.requires("gtest/cci.20210126")
+        self.requires("nlohmann_json/3.11.1")

docs/Doxyfile.in

@@ -1425,17 +1425,6 @@ EXT_LINKS_IN_WINDOW    = NO
 
 FORMULA_FONTSIZE       = 10
 
-# Use the FORMULA_TRANPARENT tag to determine whether or not the images
-# generated for formulas are transparent PNGs. Transparent PNGs are not
-# supported properly for IE 6.0, but are supported on all modern browsers.
-#
-# Note that when changing this option you need to delete any form_*.png files in
-# the HTML output directory before the changes have effect.
-# The default value is: YES.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-FORMULA_TRANSPARENT    = YES
-
 # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see
 # http://www.mathjax.org) which uses client side Javascript for the rendering
 # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX
@@ -1578,7 +1567,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = NO
+GENERATE_LATEX         = YES
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1714,16 +1703,6 @@ LATEX_BATCHMODE        = NO
 
 LATEX_HIDE_INDICES     = NO
 
-# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source
-# code with syntax highlighting in the LaTeX output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_SOURCE_CODE      = NO
-
 # The LATEX_BIB_STYLE tag can be used to specify the style to use for the
 # bibliography, e.g. plainnat, or ieeetr. See
 # http://en.wikipedia.org/wiki/BibTeX and \cite for more info.
@@ -1796,16 +1775,6 @@ RTF_STYLESHEET_FILE    =
 
 RTF_EXTENSIONS_FILE    =
 
-# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code
-# with syntax highlighting in the RTF output.
-#
-# Note that which sources are shown also depends on other settings such as
-# SOURCE_BROWSER.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_RTF is set to YES.
-
-RTF_SOURCE_CODE        = NO
-
 #---------------------------------------------------------------------------
 # Configuration options related to the man page output
 #---------------------------------------------------------------------------
@@ -1895,15 +1864,6 @@ GENERATE_DOCBOOK       = NO
 
 DOCBOOK_OUTPUT         = docbook
 
-# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the
-# program listings (including syntax highlighting and cross-referencing
-# information) to the DOCBOOK output. Note that enabling this will significantly
-# increase the size of the DOCBOOK output.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_DOCBOOK is set to YES.
-
-DOCBOOK_PROGRAMLISTING = NO
-
 #---------------------------------------------------------------------------
 # Configuration options for the AutoGen Definitions output
 #---------------------------------------------------------------------------
@@ -2082,15 +2042,6 @@ EXTERNAL_PAGES         = YES
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 
-# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram
-# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to
-# NO turns the diagrams off. Note that this option also works with HAVE_DOT
-# disabled, but it is recommended to install and use dot, since it yields more
-# powerful graphs.
-# The default value is: YES.
-
-CLASS_DIAGRAMS         = YES
-
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
 # DIA_PATH tag allows you to specify the directory where the dia binary resides.
@@ -2123,30 +2074,6 @@ HAVE_DOT               = NO
 
 DOT_NUM_THREADS        = 0
 
-# When you want a differently looking font in the dot files that doxygen
-# generates you can specify the font name using DOT_FONTNAME. You need to make
-# sure dot is able to find the font, which can be done by putting it in a
-# standard location or by setting the DOTFONTPATH environment variable or by
-# setting DOT_FONTPATH to the directory containing the font.
-# The default value is: Helvetica.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTNAME           = Helvetica
-
-# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of
-# dot graphs.
-# Minimum value: 4, maximum value: 24, default value: 10.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTSIZE           = 10
-
-# By default doxygen will tell dot to use the default font as specified with
-# DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set
-# the path where dot can find it using this tag.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_FONTPATH           =
-
 # If the CLASS_GRAPH tag is set to YES then doxygen will generate a graph for
 # each documented class showing the direct and indirect inheritance relations.
 # Setting this tag to YES will force the CLASS_DIAGRAMS tag to NO.
@@ -2347,18 +2274,6 @@ DOT_GRAPH_MAX_NODES    = 50
 
 MAX_DOT_GRAPH_DEPTH    = 0
 
-# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
-# background. This is disabled by default, because dot on Windows does not seem
-# to support this out of the box.
-#
-# Warning: Depending on the platform used, enabling this option may lead to
-# badly anti-aliased labels on the edges of a graph (i.e. they become hard to
-# read).
-# The default value is: NO.
-# This tag requires that the tag HAVE_DOT is set to YES.
-
-DOT_TRANSPARENT        = NO
-
 # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output
 # files in one run (i.e. multiple -o and -T options on the command line). This
 # makes dot run faster, but since only newer versions of dot (>1.8.10) support

docs/abm.rst

@@ -0,0 +1,40 @@
+About Agent-Based Models
+========================
+
+Agent-based models (ABM) are a type of computational model used
+to simulate the behavior of autonomous agents within a system. These
+agents can be individuals, groups, organizations, or other entities
+that interact with one another and with their environment.
+
+One of the key features of ABMs is that they focus on the micro-level
+interactions between individual agents, rather than aggregating
+data to study macro-level phenomena. This allows for the examination
+of complex behaviors that emerge from the interactions between
+agents, such as the spread of a disease or the formation of social
+networks.
+
+ABMs are often used in fields such as economics, sociology, and
+biology to study the behavior of individuals and groups. They can
+also be used to simulate the effects of different policies or
+interventions on a system.
+
+In order to create an ABM, the researcher must first define the
+agents and their characteristics, such as their behavior, beliefs,
+and goals. They must also define the rules of interaction between
+the agents and their environment. Once these parameters are set,
+the model can be run to simulate the behavior of the agents over
+time.
+
+ABMs are a powerful tool for understanding complex systems, but
+they also have their limitations. Because they focus on micro-level
+interactions, they may not accurately capture macro-level phenomena.
+Additionally, they often require a significant amount of computational
+resources and can be difficult to validate.
+
+Overall, agent-based models are a valuable tool for understanding
+the behavior of complex systems and the emergence of complex behaviors
+from the interactions between individuals. However, it is important
+to use them in conjunction with other methods to fully understand
+the system being studied.
+
+..  toctree::

docs/changelog.rst

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+- :release:`0.7.0 <2023.01.22>`
+- :support:`0` Added a minimal example and tutorial
+- :support:`0` Added documentation for each example
+- :feature:`0` Readded step() to the Model interface
+- :feature:`0` Moved to exception-based error handling
+- :feature:`0` Added Bank Reserves model to demonstrate reporting
+- :feature:`0` Added data collecting and reporting modules
+- :feature:`0` Added some useful constants, for use as random seeds
+- :feature:`0` Switched from ranlux24 to mt19937 due to speed
+- :feature:`0` Added distance measures to grid coordinate objects
+
 - :release:`0.6.0 <2022.08.19>`
 - :feature:`0` Added a to do list to the documentation
 - :feature:`0` Completed basic unit tests

docs/conf.py

@@ -27,7 +27,7 @@ def configureDoxyfile(input_dir, output_dir):
 # -- Project information -----------------------------------------------------
 
 project = 'Kami'
-copyright = '2020-2022 The Johns Hopkins University Applied Physics Laboratory LLC'
+copyright = '2020-2023 The Johns Hopkins University Applied Physics Laboratory LLC'
 author = 'James P. Howard, II <james.howard@jhu.edu>'
 
 # -- General configuration ---------------------------------------------------
@@ -94,11 +94,11 @@ def configureDoxyfile(input_dir, output_dir):
 # The short X.Y version.
 github_ref = os.getenv("GITHUB_REF", "")
 if github_ref == "":
-    git_ref = "master"
+    git_ref = "main"
 else:
     match = re.match(r"refs/(heads|tags|pull)/(?P<ref>.+)", github_ref)
     if not match:
-        git_ref = "master"
+        git_ref = "main"
     else:
         git_ref = match.group("ref")