AGVis Update 4.0

.github/workflows/test.yml

@@ -0,0 +1,20 @@
+on:
+  push:
+    branches: [ "master", "develop", "unittesting" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  test:
+    name: Run test suite
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Build the Docker image
+      run: ./go.sh build
+
+    - name: Run tests
+      run: ./go.sh run_tests

CITATION.bib

@@ -0,0 +1,10 @@
+@INPROCEEDINGS{10318583,
+  author={Parsly, Nicholas and Wang, Jinning and West, Nick and Zhang, Qiwei and Cui, Hantao and Li, Fangxing},
+  booktitle={2023 North American Power Symposium (NAPS)}, 
+  title={DiME and AGVis: A Distributed Messaging Environment and Geographical Visualizer for Large-Scale Power System Simulation}, 
+  year={2023},
+  volume={},
+  number={},
+  pages={1-5},
+  keywords={Power system simulation;Data visualization;Distributed databases;Nonhomogeneous media;Real-time systems;Power systems;North America;Power grid;Open-source software;Large-scale system;High-concurrency Data;Geovisualization;Digital twin},
+  doi={10.1109/NAPS58826.2023.10318583}}

Dockerfile

@@ -1,5 +1,6 @@
 # Start with a base Python 3.10 image from the Debian Buster distribution
 FROM python:3.10-buster AS base
+ARG BRANCH_NAME
 
 # Switch to the root user and set the working directory to /root
 USER root
@@ -18,14 +19,12 @@ RUN apt update \
         libev-dev \
     && rm -rf /var/lib/apt/lists/*
 
+RUN python3 -m pip install --upgrade pip
+
 # Install the necessary Python packages
 RUN python3 -m pip install \
         kvxopt \
         git+https://github.com/cuihantao/andes.git@develop \
-        --no-cache-dir \
-    && python3 -m pip install \
-        git+https://github.com/zmalkmus/agvisdev.git \
-        # git+https://github.com/CURENT/agvis.git \
         --no-cache-dir
 
 # Create a new user named 'cui' and a work directory
@@ -50,6 +49,11 @@ RUN git clone https://github.com/CURENT/dime.git && \
     rm -rf dime \
     && rm -rf /tmp/dime
 
+RUN git clone --single-branch --branch unittesting https://github.com/CURENT/agvis.git && \
+    cd agvis && \
+    python3 -m pip install -e . && \
+    cd ..
+
 # Switch to the 'cui' user and set the working directory to the new user's work directory
 USER cui
 WORKDIR /home/cui/work
@@ -62,4 +66,4 @@ COPY . .
 
 # Set the entrypoint and command for the container
 ENTRYPOINT []
-CMD []
+CMD []

README.md

@@ -36,13 +36,13 @@ AGVis is currently under active development. Use the following resources to get
 + Report bugs or issues by submitting a [GitHub issue][GitHub issues]
 + Submit contributions using [pull requests][GitHub pull requests]
 + Read release notes highlighted [here][release notes]
-+ Check out and cite our [paper][arxiv paper]
++ Check out and cite our [paper][naps paper]
 
 # Citing AGVis
 
 If you use AGVis for research or consulting, please cite the following publications in your publication:
 
-> Parsly, N., Wang, J., West, N., Zhang, Q., Cui, H., & Li, F. (2022). "DiME and AGVIS A Distributed Messaging Environment and Geographical Visualizer for Large-scale Power System Simulation". arXiv. https://doi.org/https://arxiv.org/abs/2211.11990v1
+> N. Parsly, J. Wang, N. West, Q. Zhang, H. Cui and F. Li, "DiME and AGVis: A Distributed Messaging Environment and Geographical Visualizer for Large-Scale Power System Simulation," 2023 North American Power Symposium (NAPS), Asheville, NC, USA, 2023, pp. 1-5, doi: 10.1109/NAPS58826.2023.10318583.
 
 Please refer as **LTB AGVis** for the first occurence and then refer as **AGVis**.
 
@@ -70,7 +70,7 @@ AGVis is licensed under [GPL v3 License](./LICENSE)
 [readthedocs]: https://agvis.readthedocs.io
 [advanced usage]: https://agvis.readthedocs.io/en/latest/usage/index.html
 [release notes]: https://agvis.readthedocs.io/en/latest/release-notes.html
-[arxiv paper]: https://arxiv.org/abs/2211.11990
+[naps paper]: https://ieeexplore.ieee.org/document/10318583
 [tutorial]: https://agvis.readthedocs.io/en/latest/getting_started/tutorial/index.html
 [LTB Repository]: https://github.com/CURENT
 [Visualization Gallery]: https://ltb.readthedocs.io/projects/agvis/en/latest/getting_started/testcases.html#visualization-gallery

agvis/__init__.py

@@ -2,7 +2,7 @@
 __version__ = _version.get_versions()['version']
 
 from agvis.main import config_logger  # NOQA
-from agvis.app import run_app
+from agvis.web import AgvisWeb
 
 __author__ = 'Nicholas West, Nicholas Parsly, Zack Malkmus, and Jinning Wang'
 

agvis/cli.py

@@ -43,6 +43,7 @@ def create_parser():
     run = sub_parsers.add_parser('run')
     run.add_argument('--host', default='127.0.0.1', help='Host to bind the server (default: 127.0.0.1)')
     run.add_argument('--port', default=8810, type=int, help='Port to bind the server (default: 8810)')
+    run.add_argument('--dev', default=False, type=bool, help='Run AGVis in development mode (default: False)')
     # run.add_argument('--static', default=None, help='Static path to serve (default: None)')
 
     misc = sub_parsers.add_parser('misc')

agvis/flask_configurations.py

@@ -0,0 +1,21 @@
+# ================================================================================
+# File Name:   flask_configurations.py
+# Author:      Zack Malkmus
+# Date:        1/18/2024 (created)
+# Description: Configuration file for FLASK APP
+# ================================================================================
+
+class DefaultConfig(object):
+    DEBUG = False
+    TESTING = False
+    CSRF_ENABLED = True
+
+class ProductionConfig(DefaultConfig):
+    DEBUG = False
+
+class DevelopmentConfig(DefaultConfig):
+    DEVELOPMENT = True
+    DEBUG = True
+
+class TestingConfig(DefaultConfig):
+    TESTING = True

agvis/main.py

@@ -12,10 +12,15 @@
 from ._version import get_versions
 
 from andes.utils.misc import is_interactive
+
 import agvis
+from agvis.web import AgvisWeb
 
-logger = logging.getLogger(__name__)
+agvis_web = AgvisWeb()
 
+app = agvis_web.app
+
+logger = logging.getLogger(__name__)
 
 def config_logger(stream_level=logging.INFO, *,
                   stream=True,
@@ -171,8 +176,8 @@ def remove_output(recursive=False):
 
 
 def run(filename='', input_path='', verbose=20,
-        host='localhost', port=8810, socket_path=None,
-        static=None,
+        host='localhost', port=8810, dev=False,
+        socket_path=None, static=None,
         **kwargs):
     """
     Entry point to run AGVis.
@@ -209,7 +214,7 @@ def run(filename='', input_path='', verbose=20,
     cases = _find_cases(filename, input_path) #NOQA
 
     # Run the flask web app
-    agvis.app.run_app("agvis.app:app", host=host, port=port)
+    agvis_web.run(host=host, port=port, dev=dev)
 
     return True
 
@@ -266,7 +271,7 @@ def print_license():
     print(f"""
     AGVis version {agvis.__version__}
 
-    Copyright (c) 2020-2023 Nick West, Nicholas Parsly, Jinning Wang
+    Copyright (c) 2020-2024 Nick West, Nicholas Parsly, Jinning Wang
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by

agvis/static/js/CanvasLayer.js

@@ -1,3 +1,31 @@
+/* ****************************************************************************************
+ * File Name:   CanvasLayer.js
+ * Authors:     Nicholas West, Nicholas Parsley
+ * Date:        9/28/2023 (last modified)
+ * 
+ * Description: CanvasLayer class. The CanvasLayer is an intermediary class, extending 
+ * 				from Leaflet’s Layer class and being extended from by most of the other 
+ * 				Layer-type classes in AGVis.Contains basic functions for rendering, 
+ * 				removing, and adding layers to the map.
+ * 
+ * API Docs:    https://ltb.readthedocs.io/projects/agvis/en/latest/modeling/canvas.html
+ * ****************************************************************************************/
+
+/**
+ * @class CanvasLayer
+ * @extends {L.Layer}
+ * 
+ * @param   {Object} options
+ * 
+ * @var {Map}                 _map                   - The leaflet map passed from the Window.
+ * @var {HTML Canvas Element} _canvas                - The canvas element that will be drawn on.
+ * @var {Boolean}             _needsProjectionUpdate - Determines whether the Layer’s projection needs to be updated.
+ * @var {Point}               size					 - Represents the current size of the map in pixels.
+ * @var {LatLngBounds}        bounds			     - Represents the geographical bounds of the map.
+ * @var {Function}            project				 - The latLngToContainerPoint function specifically for CanvasLayer._map.
+ * 
+ * @returns {CanvasLayer}
+ */
 L.CanvasLayer = L.Layer.extend({
 
 	options: {
@@ -7,10 +35,25 @@ L.CanvasLayer = L.Layer.extend({
 		repeat: false,
 	},
 
+	/**
+	 * Initializes the canvas layer with options
+	 * 
+	 * @memberof CanvasLayer
+	 * @param   {Object} options 
+	 * @returns
+	 */
 	initialize(options) {
 		L.Util.setOptions(this, options);
 	},
 
+	/**
+	 * Creates the canvas element and appends it to the map.
+	 * Establishes how resizing works for the Layer.
+	 * 
+	 * @memberof CanvasLayer
+	 * @param   {Object} map
+	 * @returns
+	 */
 	onAdd(map) {
 		this._map = map;
 		this._canvas = L.DomUtil.create('canvas', 'leaflet-canvas-layer');
@@ -30,13 +73,26 @@ L.CanvasLayer = L.Layer.extend({
 		this._reset();
 	},
 
+	/**
+	 * Redraws the canvas layer
+	 *
+	 * @memberof CanvasLayer
+	 * @returns
+	 */
 	redraw() {
 		if (!this._frame) {
 			this._frame = L.Util.requestAnimFrame(this._redraw, this);
 		}
 		return this;
 	},
 
+	/**
+	 * Clean up for the canvas layer
+	 * 
+	 * @memberof CanvasLayer
+	 * @param   {Object} map
+	 * @returns
+	 */
 	onRemove(map) {
 		this._map.getPane('overlayPane').removeChild(this._canvas);
 
@@ -47,23 +103,52 @@ L.CanvasLayer = L.Layer.extend({
 		this._map = null;
 	},
 
+	/**
+	 * Adds the canvas layer to the map
+	 * 
+	 * @memberof CanvasLayer
+	 * @param   {Object} map
+	 * @returns {Object} CanvasLayer object
+	 */
 	addTo(map) {
 		map.addLayer(this);
 		return this;
 	},
 
+	/**
+	 * Resizes the canvas layer from a resize event
+	 * 
+	 * @memberof CanvasLayer
+	 * @param   {Object} resizeEvent
+	 * @returns
+	 */
 	_resize(resizeEvent) {
 		this._canvas.width = this._map.getSize().x;
 		this._canvas.height = this._map.getSize().y;
 	},
 
+	/**
+	 * Initially starts drawing the Layer. Sets the position of the canvas 
+	 * and requests a projection update.
+	 * 
+	 * @memberof CanvasLayer
+	 * @returns
+	 */
 	_reset() {
 		var topLeft = this._map.containerPointToLayerPoint([0, 0]);
 		L.DomUtil.setPosition(this._canvas, topLeft);
 		this._needsProjectionUpdate = true;
 		this.redraw();
 	},
 
+	/**
+	 * Calls the rendering function for a given Layer if it has one. 
+	 * Sets up the variables mentioned above that are passed to the Topology-type 
+	 * and Contour-type Layers.
+	 * 
+	 * @memberof CanvasLayer
+	 * @returns
+	 */
 	_redraw() {
 		const size = this._map.getSize();
 		const bounds = this._map.getBounds();