3.1 release

gramian · Oct 1, 2020 · 09759b6 · 09759b6
1 parent 4f9bc9b
commit 09759b6
Show file tree

Hide file tree

Showing 6 changed files with 58 additions and 59 deletions.
diff --git a/CODE b/CODE
@@ -1,8 +1,8 @@
 # code.ini
 name: Hierarchical Approximate Proper Orthogonal Decomposition
 shortname: hapod
-version: 3.0
-release-date: 2020-01-24
+version: 3.1
+release-date: 2020-10-01
 author: Christian Himpe, Stephan Rave
 orcid: 0000-0003-2194-6754, 0000-0003-0439-7212
 topic: Science, Mathematics, Dimension Reduction
@@ -12,7 +12,7 @@ license-type: open-source
 repository: github.com/gramian/hapod
 repository-type: git
 language: Matlab
-dependencies: Octave >=4.2, Matlab >=2013b
+dependencies: Octave >=4.0, Matlab >=2013b
 systems: Linux, Windows
 website: git.io/hapod
 keywords: Singular Value Decomposition, Principal Component Analysis, Proper Orthogonal Decomposition, Dimension Reduction, Data Compression
diff --git a/CONTRIBUTORS b/CONTRIBUTORS
@@ -1,3 +1,3 @@
-[Christian Himpe](https://orcid.org/0000-0003-2194-6754): Design, Architecture, Coding, Testing, Debugging, Documentation, Maintenance, Support, Management
-[Stephan Rave](https://orcid.org/0000-0003-0439-7212): Coding, Testing, Debugging
-CSC Scientific Computing Team, led by: [Jens Saak](https://orcid.org/0000-0001-5567-9637): Testing, Code Review
+* [Christian Himpe](https://orcid.org/0000-0003-2194-6754): Design, Architecture, Coding, Testing, Debugging, Documentation, Maintenance, Support, Management
+* [Stephan Rave](https://orcid.org/0000-0003-0439-7212): Coding, Testing, Debugging
+* CSC Scientific Computing Team, led by: [Jens Saak](https://orcid.org/0000-0001-5567-9637): Testing, Code Review
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@ HAPOD - Hierarchical Approximate Proper Orthogonal Decomposition
 ================================================================
 
 * HAPOD - Hierarchical Approximate POD
-* version: 3.0 (2020-01-24)
+* version: 3.1 (2020-10-01)
 * by: C. Himpe (0000-0003-2194-6754), S. Rave (0000-0003-0439-7212)
 * under: BSD 2-Clause License (opensource.org/licenses/BSD-2-Clause)
 * summary: Fast distributed or incremental POD computation.
@@ -11,6 +11,7 @@ HAPOD - Hierarchical Approximate Proper Orthogonal Decomposition
 
 * Proper Orthogonal Decomposition (POD)
 * Singular Value Decomposition (SVD)
+* Principal Axis Transformation (PAT)
 * Principal Component Analysis (PCA)
 * Empirical Orthogonal Functions (EOF)
 * Karhunen-Loeve Transformation (KLT)
@@ -22,30 +23,32 @@ HAPOD - Hierarchical Approximate Proper Orthogonal Decomposition
 * Model Reduction
 * Low-Rank Approximation
 * Data Compression
+* Unsupervised Learning
 
 ## Features
 
 * Error-driven
+* Rigorous bounds
 * Single pass (each data vector is needed only once)
 * Column-wise data partition
 * Custom SVD backends
 
 ## Functionality
 
 * Standard POD
-* Incremental HAPOD -> for memory-limited environments: single-board-computers
-* Distributed HAPOD -> for distributd memory environments: super-computers
+* Incremental HAPOD -> for memory-limited environments, e.g. single-board-computers
+* Distributed HAPOD -> for distributd memory environments, e.g. super-computers
 * Distributed-of-Incremental HAPOD
 
 ## Algorithm
 
-C. Himpe, T. Leibner and S. Rave.
-"[Hierarchical Approximate Proper Orthogonal Decomposition](http://hdl.handle.net/21.11116/0000-0002-5342-6)".
+C. Himpe, T. Leibner, S. Rave:
+"[Hierarchical Approximate Proper Orthogonal Decomposition](http://hdl.handle.net/21.11116/0000-0002-5342-6)";
 SIAM Journal on Scientific Computing, 40(5): A3267--A3292, 2018.
 
 ## Compatibility
 
-* GNU Octave >= 4.2
+* GNU Octave >= 4.0
 * Mathworks MATLAB >= 2013b
 
 ## Basic Usage
@@ -108,7 +111,7 @@ sub-tree:
 
 The argument `meta` only needs to be passed for topology argument `incr_r`,
 `dist_r` and `incr_1` unless it is first leaf. This means especially the user
-never has to create such a structure, as if it is required it is given as a
+never has to create such a structure, since if it is required it is given as a
 previous return value.
 
 ## Custom SVD
@@ -120,7 +123,7 @@ handle with the following signature:
 [U,d] = mysvd(X)
 ```
 
-for a data matrix `X`, and return left singular vectors in matrix `U` and
+for a data matrix `X`, and returning left singular vectors in matrix `U` and
 singular values in column vector `d`. By default (or `mysvd` = `eco`) a standard
 rank-revealing SVD is used. Additionally, by `mysvd` = `mos` the method of
 snapshots can be selected.
@@ -138,30 +141,35 @@ as a template.
 
 ## Cite As
 
-C. Himpe, T. Leibner and S. Rave.
-"[Hierarchical Approximate Proper Orthogonal Decomposition](https://doi.org/10.1137/16M1085413)".
+C. Himpe, T. Leibner and S. Rave:
+"[Hierarchical Approximate Proper Orthogonal Decomposition](https://doi.org/10.1137/16M1085413)";
 SIAM Journal on Scientific Computing, 40(5): A3267--A3292, 2018.
 
 ## Used In
 
-* P. Benner, C. Himpe.
-"[Cross-Gramian-Based Dominant Subspaces](https://doi.org/10.1007/s10444-019-09724-7)".
+* P. Benner, C. Himpe:
+"[Cross-Gramian-Based Dominant Subspaces](https://doi.org/10.1007/s10444-019-09724-7)";
 Advances in Computational Mathematics, 45(5): 2533--2553, 2019.
 
-* C. Himpe, T. Leibner, S. Rave, J. Saak.
-"[Fast Low-Rank Empirical Cross Gramians](https://doi.org/10.1002/pamm.201710388)".
-Proceedings in Applied Mathematics and Mechanics, 17: 841--842, 2017.
+* B.J. Beach:
+"[An Implementation-Based Exploration of HAPOD: Hierarchical Approximate Proper Orthogonal Decomposition](http://hdl.handle.net/10919/81938)";
+Virgina Tech, Master Thesis, 2018.
 
-* C. Himpe, T. Leibner, S. Rave.
-"[Comprehensive Memory-Bound Simulations on Single Board Computers](https://doi.org/10.5281/zenodo.814497)".
-Extended Abstract, 2nd Conference on Power Aware Computing (PACO), 2017.
+* C. Himpe, T. Leibner, S. Rave, J. Saak:
+"[Fast Low-Rank Empirical Cross Gramians](https://doi.org/10.1002/pamm.201710388)";
+Proceedings in Applied Mathematics and Mechanics, 17: 841--842, 2017.
 
 ## See Also
 
-* C. Himpe, T. Leibner, S. Rave.
-"[HAPOD - Fast, Simple and Reliable Distributed POD Computation](https://doi.org/10.11128/arep.55.a55283)".
+* C. Himpe, T. Leibner, S. Rave:
+"[HAPOD - Fast, Simple and Reliable Distributed POD Computation](https://doi.org/10.11128/arep.55.a55283)";
 ARGESIM Report 55 (MATHMOD 2018 Volume): 119--120, 2018.
 
+* C. Himpe, T. Leibner, S. Rave:
+"[Comprehensive Memory-Bound Simulations on Single Board Computers](https://doi.org/10.5281/zenodo.814497)";
+Extended Abstract, 2nd Conference on Power Aware Computing (PACO), 2017.
+
 * C. Himpe and S. Rave.
 "[HAPOD - Hierarchical Approximate POD](https://himpe.science/poster/rave16_morml.pdf)".
 Data-Driven Model Order Reduction and Machine Learning (MORML), 2016.
+
diff --git a/RUNME.m b/RUNME.m
@@ -1,23 +1,23 @@
 function RUNME()
 %%% project: hapod - Hierarchical Approximate POD ( https://git.io/hapod )
-%%% version: 3.0 (2020-01-24)
+%%% version: 3.1 (2020-10-01)
 %%% authors: C. Himpe (0000-0003-2194-6754), S. Rave (0000-0003-0439-7212)
 %%% license: BSD 2-Clause License (opensource.org/licenses/BSD-2-Clause)
 %%% summary: Basic tests for incremental HAPOD and distributed HAPOD
 
 %% Generate test data
 
-    randn('seed',1009);			   % seed random number generator
-    n = 16;				   % set number of partitions
-    N = n*n;				   % set test problem size
-    [a,~,c] = svd(randn(N,N));		   % compute SVD of normal random matrix
-    b = logspace(0,-16,N)';		   % artificial singular values
-    s = a*diag(b)*c';	 		   % reassign singular values
-    S = mat2cell(s,size(s,1),n*ones(n,1)); % split data matrix into partitions
-    w = 0.5;				   % relaxation parameter omega
-    E = sqrt(eps);			   % target mean L2 projection error
+    randn('seed',1009);			% seed random number generator
+    n = 32;					% set number of partitions
+    N = n*n;					% set test problem size
+    [a,~,c] = svd(randn(N,N));			% compute SVD of random matrix
+    b = logspace(0,-16,N)';			% artificial singular values
+    s = a*diag(b)*c';	 			% reassign singular values
+    S = mat2cell(s,size(s,1),n*ones(n,1));	% split data into partitions
+    w = 0.5;					% relaxation parameter omega
+    E = sqrt(eps);				% target mean L2 error
 
-    meanl2 = @(U) norm(s-U*(U'*s),'fro') / sqrt(N); % tested mean L2 error
+    meanl2 = @(U) norm(s-U*(U'*s),'fro') / sqrt(N);	% tested mean L2 error
 
     disp(' ');
     HAPOD_VERSION = hapod('version')
@@ -42,7 +42,7 @@ function RUNME()
     disp(' ');
 
     % Determine mode bound
-    [Uloc,~,~] = hapod(S,E*w,'none');
+    [Uloc,~,~] = hapod(S,E*sqrt(1-w^2)/sqrt(n-1),'none');
     local_mode_bound = size(Uloc,2)
     disp(' ');
 

diff --git a/VERSION b/VERSION
@@ -0,0 +1,2 @@
+3.1
+
diff --git a/hapod.m b/hapod.m
@@ -1,6 +1,6 @@
 function [svec,sval,meta] = hapod(data,bound,topo,relax,meta,depth,mysvd)
 %%% project: hapod - Hierarchical Approximate POD ( https://git.io/hapod )
-%%% version: 3.0 (2020-01-24)
+%%% version: 3.1 (2020-10-01)
 %%% authors: C. Himpe (0000-0003-2194-6754), S. Rave (0000-0003-0439-7212)
 %%% license: BSD 2-Clause License (opensource.org/licenses/BSD-2-Clause)
 %%% summary: Fast distributed or incremental POD computation.
@@ -11,7 +11,7 @@
 % DESCRIPTION:
 %  The hierarchical approximate proper orthogonal decomposition (HAPOD) is a
 %  tree-based algorithm to compute low-rank representations of column-wise
-%  partitioned data matrices, of which the special cases of incremental HAPOD 
+%  partitioned data matrices, of which the special cases of incremental HAPOD
 %  and distributed HAPOD are implemented. The HAPOD is an error-driven POD
 %  method with low communication for distributed memory systems as well as
 %  for memory-limited shared memory systems.
@@ -55,7 +55,7 @@
 %  incr_1 and dist_1 should be used for the child nodes of the associated HAPOD
 %  tree, while the topologies: incr_r and dist_r should be used for the root
 %  node. The returned information structure (or a cell-array thereof) can be
-%  passed to the parent nodes in the associated HAPOD tree. 
+%  passed to the parent nodes in the associated HAPOD tree.
 %
 % CITE AS:
 %  C. Himpe, T. Leibner and S. Rave.
@@ -72,7 +72,7 @@
 %
 % Further information: https://git.io/hapod
 
-    if strcmp(data,'version'), svec = 3.0; return; end%if
+    if strcmp(data,'version'), svec = 3.1; return; end%if
 
     % Default arguments
     if nargin<3 || isempty(topo),  topo  = 'none'; end%if
@@ -93,25 +93,13 @@
     end%if
 
     % Argument validation
-    if not(isnumeric(bound) && isscalar(bound) && bound>0)
+    assert(isnumeric(bound) && isscalar(bound) && bound>0,'hapod: bad bound!');
 
-        error('hapod: bad bound!');
-    end%if
-
-    if not(isnumeric(relax) && isscalar(relax) && relax>0 && relax<=1)
-
-        error('hapod: bad relax!');
-    end%if
-
-    if strcmp(topo,'incr_1') && (not(isscalar(depth)) || not(mod(depth,1)==0) || depth<2)
+    assert(isnumeric(relax) && isscalar(relax) && relax>0 && relax<=1,'hapod: bad relax!');
 
-        error('hapod: bad depth!');
-    end%if
-
-    if any(strcmp(topo,{'incr_r','dist_r'})) && isempty(meta)
+    assert(not(strcmp(topo,'incr_1')) || isscalar(depth) || depth<2 || (mod(depth,1)==0),'hapod: bad depth!');
 
-        error('hapod: missing meta!');
-    end%if
+    assert(not(strcmp(topo,'incr_r')) || not(strcmp(topo,'dist_r')) || isempty(meta),'hapod: missing meta!');
 
     % Precompute common quantities
     nodeBound = bound * sqrt(1.0 - relax^2);
@@ -160,7 +148,7 @@
 
             [svec,sval,meta] = dist_r(svec,rootBound,meta,mysvd);
 
-        case 'none' % Standard POD
+        case 'none'   % Standard POD
 
             tId = tic();
             meta.nSnapshots = sum(cellfun(@(M) size(M,2),data));
@@ -276,3 +264,4 @@
     [d,L] = sort(sqrt(abs(diag(V))),'descend');
     U = X * bsxfun(@rdivide,E(:,L),d');
 end
+