LogoActions <a href = "https://github.com/danielvartan/logoactions"><img src = "images/logo.svg" align="right" width="120" /></a>

<!-- badges: start -->

<!-- badges: end -->

Overview

LogoActions is a collection of GitHub Actions designed to facilitate the setup and execution of NetLogo models within GitHub workflows. These actions enable researchers and developers to automate the installation of NetLogo, run and test simulations, and integrate NetLogo with other tools and platforms, such as Quarto, logolink and pyNetLogo.

Currently, the repository includes:

• setup-netlogo: Installs NetLogo on the runner machine
• check-netlogo: Runs all BehaviorSpace experiments in a repository's NetLogo models to verify they execute without errors

Along with these actions, a series of workflows examples are provided to demonstrate how to use the action in practice. See the Usage section below for more details.

If you find this project useful, please consider giving it a star!  

The continuous development of LogoActions depends on community support. If you can afford to do so, please consider becoming a sponsor.  

Usage

Check NetLogo Models

This workflow shows how to use the check-netlogo action to automatically verify that all BehaviorSpace experiments in a repository's NetLogo models run without errors. This is particularly useful for continuous integration (CI) workflows, ensuring that any changes to the models or experiments do not introduce issues.

You can view this workflow in action on the repository's actions page. See the LogoClim model for a real-world example of how this action can catch errors early in the development process.

Below is a basic workflow configuration. To use it, create a file named check-netlogo.yaml with the content below and place it in the .github/workflows folder at the root of your repository.

on:
  push:
    branches: [main, master]

name: NetLogo check
permissions: read-all

jobs:
  check-netlogo:
    name: Check NetLogo models
    runs-on: ubuntu-latest
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up NetLogo
        uses: danielvartan/logoactions/setup-netlogo@v1

      - name: Check NetLogo models
        uses: danielvartan/logoactions/check-netlogo@v1

Run BehaviorSpace Experiments

This workflow shows how to set up NetLogo and run BehaviorSpace experiments in headless mode. Experiment results are saved as CSV files and uploaded as artifacts for later retrieval. This approach is useful for automating simulation runs, conducting parameter sweeps, or integrating NetLogo experiments into data analysis pipelines.

You can view this workflow in action on the repository's actions page. The complete workflow file is available here.

Below is a basic workflow configuration.

on:
  push:
    branches: [main, master]

name: Run BehaviorSpace experiments
permissions: read-all

jobs:
  run-experiments:
    name: Run experiments
    runs-on: ubuntu-latest
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Set up NetLogo
        uses: danielvartan/logoactions/setup-netlogo@v1

      - name: Create artifacts directory
        id: artifacts-dir
        run: |
          # Create artifacts directory

          artifacts_dir="${RUNNER_TEMP}/artifacts"
          mkdir -p "${artifacts_dir}"

          echo "path=${artifacts_dir}" >> "${GITHUB_OUTPUT}"
        shell: bash

      - name: Run experiment
        run: |
          # Run experiment

          artifacts_dir="${{ steps.artifacts-dir.outputs.path }}"
          model_dir="${NETLOGO_HOME}/models/Sample Models/Biology"
          model_file='Wolf Sheep Predation.nlogox'
          experiment_name='Wolf Sheep Crossing'
          table_file="${artifacts_dir}/experiment-table.csv"

          netlogo \
            --headless \
            --model "${model_dir}/${model_file}" \
            --experiment "${experiment_name}" \
            --table "${table_file}"

          cat "${table_file}"
        shell: bash

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: experiments-output
          path: ${{ steps.artifacts-dir.outputs.path }}
          retention-days: 90

Run Experiments with Quarto and logolink

This workflow shows how to combine NetLogo with Quarto and the logolink R package to run experiments and generate reproducible reports. It installs all required dependencies, renders the Quarto document, and deploys the output to GitHub Pages. An example report is available here.

You can view this workflow in action on the repository's actions page. The complete workflow file is available here.

Below is a basic workflow configuration.

on:
  push:
    branches: [main, master]

name: Run experiments with Quarto and logolink
permissions: read-all

jobs:
  run-logolink:
    runs-on: ubuntu-latest
    name: Run experiments
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    permissions:
      contents: write
      pages: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up NetLogo
        uses: danielvartan/logoactions/setup-netlogo@v1

      - name: Set up R
        uses: r-lib/actions/setup-r@v2

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Install system dependencies
        if: runner.os == 'Linux'
        run: |
          # Install system dependencies

          sudo apt-get update -qq

          sudo apt-get install -y -qq \
            libfontconfig1-dev \
            pandoc
        shell: bash

      - name: Install R dependencies
        run: |
          # Install R dependencies

          options(repos=c(CRAN="https://cloud.r-project.org"))

          install.packages(
            c(
              "rmarkdown",
              "knitr"
            )
          )
        shell: Rscript {0}

      - name: Check if renv is initialized
        id: renv-check
        run: |
          # Check if renv is initialized

          if [ -f "renv.lock" ]; then
            echo "exists=true" >> $GITHUB_OUTPUT
          else
            echo "exists=false" >> $GITHUB_OUTPUT
          fi
        shell: bash

      - name: Set up renv
        if: steps.renv-check.outputs.exists == 'true'
        uses: r-lib/actions/setup-renv@v2

      - name: Install and initialize renv
        if: steps.renv-check.outputs.exists == 'false'
        run: |
          # Install and initialize renv

          install.packages("renv")

          renv::init()
        shell: Rscript {0}

      - name: Render Quarto
        run: |
          # Render Quarto

          quarto render
        shell: bash

      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4.5.0
        with:
          clean: false
          branch: gh-pages
          folder: docs

For information on workflow RAM, storage, and time limits, refer to the GitHub Actions [usage limits](https://docs.github.com/en/actions/administering-github-actions/usage-lim