0.1.0 SparseMatrix

Author: RobTillaart

libraries/SparseMatrix/.arduino-ci.yml

@@ -0,0 +1,11 @@
+compile:
+  # Choosing to run compilation tests on 2 different Arduino platforms
+  platforms:
+    - uno
+    # - due
+    # - zero
+    # - leonardo
+    - m4
+    - esp32
+    - esp8266
+    # - mega2560

libraries/SparseMatrix/.github/workflows/arduino-lint.yml

@@ -0,0 +1,13 @@
+
+name: Arduino-lint
+
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: arduino/arduino-lint-action@v1
+        with:
+          library-manager: update
+          compliance: strict

libraries/SparseMatrix/.github/workflows/arduino_test_runner.yml

@@ -0,0 +1,17 @@
+---
+name: Arduino CI
+
+on: [push, pull_request]
+
+jobs:
+  runTest:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.6
+      - run: |
+          gem install arduino_ci
+          arduino_ci.rb

libraries/SparseMatrix/.github/workflows/jsoncheck.yml

@@ -0,0 +1,18 @@
+name: JSON check
+
+on:
+  push:
+    paths:
+      - '**.json'
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: json-syntax-check
+        uses: limitusus/json-syntax-check@v1
+        with:
+          pattern: "\\.json$"
+

libraries/SparseMatrix/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2022 Rob Tillaart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND 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.

libraries/SparseMatrix/README.md

@@ -0,0 +1,92 @@
+
+[![Arduino CI](https://github.com/RobTillaart/SparseMatrix/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
+[![Arduino-lint](https://github.com/RobTillaart/SparseMatrix/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/SparseMatrix/actions/workflows/arduino-lint.yml)
+[![JSON check](https://github.com/RobTillaart/SparseMatrix/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/SparseMatrix/actions/workflows/jsoncheck.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/SparseMatrix/blob/master/LICENSE)
+[![GitHub release](https://img.shields.io/github/release/RobTillaart/SparseMatrix.svg?maxAge=3600)](https://github.com/RobTillaart/SparseMatrix/releases)
+
+
+# SparseMatrix
+
+Arduino library for sparse matrices.
+
+
+## Description
+
+SparseMatrix is an **experimental** library to implement sparse matrices on an Arduino.
+
+The maximum matrix that can be represented is 255 x 255 
+with a maximum of 255 non-zero elements.
+This would just fit in an UNO's 2K memory.
+
+The library does not hold the dimensions of the matrix (at least in 0.1.0)
+
+The purpose of the library is efficient storage in memory. 
+It does not do math operations except sum().
+
+Relates to https://github.com/RobTillaart/distanceTable
+
+
+#### Implementation
+
+The implementation is based on 3 arrays holding ``` x, y, value``` where value is float.
+In the future other datatypes should be possible.
+
+The elements are not kept sorted or indexed so optimizations are possible
+but not investigated yet.
+
+
+## Interface
+
+- **SparseMatrix(uint8_t size)** constructor. 
+Parameter is the maximum number of elements in the sparse matrix.
+- **uint8_t size()** maximum number of elements.
+- **uint8_t count()** current number of elements in the matrix.
+- **float sum()** sum of all elements ( > 0 ) in the matrix.
+- **bool set(uint8_t x, uint8_t y, float value)** gives an element in the matrix a value.
+If the value is set to zero, it is removed from the internal store.
+Returns false if the internal store is full, true otherwise.
+- **float get(uint8_t x, uint8_t y)** returns the value in the matrix. 
+
+
+## Future
+
+- documentation
+- test
+- template version to store other data types 
+  - 1, 2, 3 (RGB), 4 byte integer or 8 byte doubles
+  - struct, complex number
+  - etc
+- add examples
+  - 2D histogram e.g. temperature vs humidity
+  - N queens game.
+- investigate optimizations.
+- should **set()** return the number of free places?
+  - no hard code and more informative than just a bool.
+- add link in distanceTable repo
+- uint16_t size for larger platforms.
+  - max matrix still 255 x 255 but more elements <> 0.
+
+
+#### new functions
+
+- **float add(uint8_t x, uint8_t y, float value)** adds value to the x,y position.
+  - add or remove an internal element if needed,
+  - functional **set(x,y, get(x,y) + value)**
+- **void clear()** sets all elements to zero again. 
+  - \_count = 0; should be sufficient.
+- walking through the elements?
+  - first -> next;  last -> prev.
+  
+
+#### won't
+
+- math
+  - determinant?
+  - M x M
+  - diagonal?
+- add examples
+  - battleship game
+  - minesweeper game
+  - nice exercise 
+

libraries/SparseMatrix/SparseMatrix.cpp

@@ -0,0 +1,115 @@
+//
+//    FILE: SparseMatrix.cpp
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.0
+//    DATE: 2022-07-12
+// PURPOSE: Arduino library for sparse matrices
+//
+//  HISTORY:
+//  0.1.0  2022-07-12  initial version
+
+
+#include "SparseMatrix.h"
+
+
+SparseMatrix::SparseMatrix(uint8_t sz)
+{
+  _count = 0;
+  _size  = sz;
+  _x     = (uint8_t *) malloc(sz);
+  _y     = (uint8_t *) malloc(sz);
+  _value = (float *)   malloc(sz * sizeof(float));
+  //  catch malloc error
+  if (_x && _y && _value) return;
+  _size = 0;
+}
+
+
+SparseMatrix::~SparseMatrix()
+{
+  if (_x) free(_x);
+  if (_y) free(_y);
+  if (_value) free(_value);
+}
+
+
+uint8_t SparseMatrix::size()
+{
+  return _size;
+}
+
+
+uint8_t SparseMatrix::count()
+{
+  return _count;
+}
+
+float SparseMatrix::sum()
+{
+  float _sum = 0;
+  for (int i = 0; i < _count; i++)
+  {
+    _sum += _value[i];
+  }
+  return _sum;
+}
+
+
+bool SparseMatrix::set(uint8_t x, uint8_t y, float value)
+{
+  int pos = findPos(x, y);
+  //  existing element
+  if (pos > -1)
+  {
+    if (value != 0.0)
+    {
+      _value[pos] = value;
+    }
+    else
+    {
+      _count--;
+      //  move last element
+      //  efficiency is not a requirement yet.
+      _x[pos] = _x[_count];
+      _y[pos] = _y[_count];
+      _value[pos] = _value[_count];
+    }
+    return true;
+  }
+
+  //  new element
+  if (_count >= _size) return false;
+  _x[_count] = x;
+  _y[_count] = y;
+  _value[_count] = value;
+  _count++;
+  return true;
+}
+
+
+float SparseMatrix::get(uint8_t x, uint8_t y)
+{
+  int pos = findPos(x, y);
+  if (pos > -1)
+  {
+    return _value[pos];
+  }
+  return 0;
+}
+
+
+int SparseMatrix::findPos(uint8_t x, uint8_t y)
+{
+  for (int i = 0; i < _count; i++)
+  {
+    if ((_x[i] == x) && (_y[i] == y))
+    {
+      return i;
+    }
+  }
+  return -1;
+}
+
+
+
+// -- END OF FILE --

libraries/SparseMatrix/SparseMatrix.h

@@ -0,0 +1,47 @@
+#pragma once
+//
+//    FILE: SparseMatrix.h
+//  AUTHOR: Rob Tillaart
+// VERSION: 0.1.0
+//    DATE: 2022-07-12
+// PURPOSE: Arduino library for sparse matrices
+//
+
+
+#include "Arduino.h"
+
+#define SPARSEMATRIX_LIB_VERSION        (F("0.1.0"))
+
+
+class SparseMatrix
+{
+public:
+  SparseMatrix(uint8_t sz);
+  ~SparseMatrix();
+
+  uint8_t  size();
+  uint8_t  count();
+  float    sum();
+
+  //  returns false if no slots free
+  //  could return # free slots?
+  bool     set(uint8_t x, uint8_t y, float value);
+  float    get(uint8_t x, uint8_t y);
+
+
+private:
+  int       _size   = 0;
+  int       _count  = 0;
+
+  uint8_t   *_x     = NULL;
+  uint8_t   *_y     = NULL;
+  float     *_value = NULL;
+
+  //  returns index of x,y if in set
+  //  otherwise -1
+  int findPos(uint8_t x, uint8_t y);
+};
+
+
+// -- END OF FILE --
+