Merge pull request #9 from sjvrijn/final-joss-update

Final joss update

changelog.txt

@@ -1,5 +1,14 @@
 since last version:
+- can now install development requirements using `pip install mf2[dev]` notation
+- conda references now point to conda-forge channel
 - updated array-generation strategy in property-test
+- removed obsolete code (himmelblau 3-fidelity)
+- Added type hints for adjustable functions
+- moved contributions section in Readme to separate CONTRIBUTING.md file
+- Tests:
+  * array-generation in property-test now uses hypothesis' numpy array strategy
+  * coverage now at 100%: Added tests for remaining uncovered code
+  * Rewrote regression tests to use pytest-regressions plugin
 - JOSS paper:
   * Fixed typo
   * Rewrote 'statement of need' paragraphs
@@ -8,7 +17,8 @@ since last version:
   * hardware and software version info now mentioned on performance page
   * example-usage separated out into separate file in docs/scripts
   * figure of example-usage improved to 600dpi
-  * page on performance added, script for plots added in docs/scripts
+  * page on performance added, script for plots added in docs/scripts, including
+    original matlab source code for borehole, currin and park91a/b
 
 
 v2020.4.3:

docs/scripts/matlab/README.md

@@ -0,0 +1,44 @@
+# Matlab files for scalability comparison
+
+This folder contains the matlab files that were used for the scalability
+comparison plots:
+
+ - Utility functions:
+
+   - `myscale.m` scales input from [0, 1] to the given new range.
+
+   - `mytiming.m` creates random input of desired size `N` and performs a timing
+     experiment akin to Python's [`timeit`].
+
+ - Test functions:
+
+   - `test_function_output.m` confirms that the matlab code gives the same
+     result as the Python code for the same input. Expects input
+     `input_<N>d.mat` and output `output_<N>d_<Name>_<Fidelity>.mat`-files to
+     be available. These can be created using [`scipy.io.savemat`] in Python.
+
+   - `test_function_performance.m` calls `mytiming.m` for all listed
+     function-fidelity combinations, with increasing evaluation sizes `N`. By
+     default, values for `N` are successive powers of 10: 10^0 -- 10^6.
+
+ - Matlab implementations of benchmark functions
+
+   The following implementations were retrieved from
+   ``https://www.sfu.ca/~ssurjano/multi.html`` on 2017-10-02, and are available
+   here under their original GNU GPL v2.0 licenses:
+
+   - [Borehole]: `borehole.m` & `boreholelc.m`
+
+   - [Currin]: `curretal88exp.m` & `curretal88explc.m`
+
+   - [Park91a]: `park91a.m` & `park91alc.m`
+
+   - [Park91b]: `park91b.m` & `park91blc.m`
+
+
+[`timeit`]: https://docs.python.org/3/library/timeit.html#timeit.Timer.autorange
+[`scipy.io.savemat`]: https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.savemat.html#scipy.io.savemat
+[Borehole]: https://www.sfu.ca/~ssurjano/borehole.html
+[Currin]: https://www.sfu.ca/~ssurjano/curretal88exp.html
+[Park91a]: https://www.sfu.ca/~ssurjano/park91a.html
+[Park91b]: https://www.sfu.ca/~ssurjano/park91b.html

docs/scripts/matlab/borehole.m

@@ -0,0 +1,53 @@
+function [y] = borehole(xx)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% BOREHOLE FUNCTION
+%
+% Authors: Sonja Surjanovic, Simon Fraser University
+%          Derek Bingham, Simon Fraser University
+% Questions/Comments: Please email Derek Bingham at [email protected].
+%
+% Copyright 2013. Derek Bingham, Simon Fraser University.
+%
+% THERE IS NO WARRANTY, EXPRESS OR IMPLIED. WE DO NOT ASSUME ANY LIABILITY
+% FOR THE USE OF THIS SOFTWARE.  If software is modified to produce
+% derivative works, such modified software should be clearly marked.
+% Additionally, 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 the Free Software Foundation; version 2.0 of the License. 
+% Accordingly, this program is distributed in the hope that it will be 
+% useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
+% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
+% General Public License for more details.
+%
+% For function details and reference information, see:
+% http://www.sfu.ca/~ssurjano/
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% OUTPUT AND INPUT:
+%
+% y  = water flow rate
+% xx = [rw, r, Tu, Hu, Tl, Hl, L, Kw]
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+rw = xx(1);
+r  = xx(2);
+Tu = xx(3);
+Hu = xx(4);
+Tl = xx(5);
+Hl = xx(6);
+L  = xx(7);
+Kw = xx(8);
+
+frac1 = 2 * pi * Tu * (Hu-Hl);
+
+frac2a = 2*L*Tu / (log(r/rw)*rw^2*Kw);
+frac2b = Tu / Tl;
+frac2 = log(r/rw) * (1+frac2a+frac2b);
+
+y = frac1 / frac2;
+
+end

docs/scripts/matlab/boreholelc.m

@@ -0,0 +1,55 @@
+function [y] = boreholelc(xx)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% BOREHOLE FUNCTION, LOWER FIDELITY CODE
+% This function is used as the "low-accuracy code" version of the function
+% borehole.m.
+%
+% Authors: Sonja Surjanovic, Simon Fraser University
+%          Derek Bingham, Simon Fraser University
+% Questions/Comments: Please email Derek Bingham at [email protected].
+%
+% Copyright 2013. Derek Bingham, Simon Fraser University.
+%
+% THERE IS NO WARRANTY, EXPRESS OR IMPLIED. WE DO NOT ASSUME ANY LIABILITY
+% FOR THE USE OF THIS SOFTWARE.  If software is modified to produce
+% derivative works, such modified software should be clearly marked.
+% Additionally, 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 the Free Software Foundation; version 2.0 of the License. 
+% Accordingly, this program is distributed in the hope that it will be 
+% useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
+% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
+% General Public License for more details.
+%
+% For function details and reference information, see:
+% http://www.sfu.ca/~ssurjano/
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% OUTPUT AND INPUT:
+%
+% y = water flow rate
+% xx = [rw, r, Tu, Hu, Tl, Hl, L, Kw]
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+rw = xx(1);
+r  = xx(2);
+Tu = xx(3);
+Hu = xx(4);
+Tl = xx(5);
+Hl = xx(6);
+L  = xx(7);
+Kw = xx(8);
+
+frac1 = 5 * Tu * (Hu-Hl);
+
+frac2a = 2*L*Tu / (log(r/rw)*rw^2*Kw);
+frac2b = Tu / Tl;
+frac2 = log(r/rw) * (1.5+frac2a+frac2b);
+
+y = frac1 / frac2;
+
+end

docs/scripts/matlab/curretal88exp.m

@@ -0,0 +1,44 @@
+function [y] = curretal88exp(xx)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% CURRIN ET AL. (1988) EXPONENTIAL FUNCTION
+%
+% Authors: Sonja Surjanovic, Simon Fraser University
+%          Derek Bingham, Simon Fraser University
+% Questions/Comments: Please email Derek Bingham at [email protected].
+%
+% Copyright 2013. Derek Bingham, Simon Fraser University.
+%
+% THERE IS NO WARRANTY, EXPRESS OR IMPLIED. WE DO NOT ASSUME ANY LIABILITY
+% FOR THE USE OF THIS SOFTWARE.  If software is modified to produce
+% derivative works, such modified software should be clearly marked.
+% Additionally, 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 the Free Software Foundation; version 2.0 of the License. 
+% Accordingly, this program is distributed in the hope that it will be 
+% useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
+% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
+% General Public License for more details.
+%
+% For function details and reference information, see:
+% http://www.sfu.ca/~ssurjano/
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% INPUT:
+%
+% xx = [x1, x2]
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+x1 = xx(1);
+x2 = xx(2);
+
+fact1 = 1 - exp(-1/(2*x2));
+fact2 = 2300*x1^3 + 1900*x1^2 + 2092*x1 + 60;
+fact3 = 100*x1^3 + 500*x1^2 + 4*x1 + 20;
+
+y = fact1 * fact2/fact3;
+
+end

docs/scripts/matlab/curretal88explc.m

@@ -0,0 +1,50 @@
+function [y] = curretal88explc(xx)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% CURRIN ET AL. (1988) EXPONENTIAL FUNCTION, LOWER FIDELITY CODE
+% Calls: curretal88exp.m
+% This function, from Xiong et al. (2013), is used as the "low-accuracy
+% code" version of the function curretal88exp.m.
+%
+% Authors: Sonja Surjanovic, Simon Fraser University
+%          Derek Bingham, Simon Fraser University
+% Questions/Comments: Please email Derek Bingham at [email protected].
+%
+% Copyright 2013. Derek Bingham, Simon Fraser University.
+%
+% THERE IS NO WARRANTY, EXPRESS OR IMPLIED. WE DO NOT ASSUME ANY LIABILITY
+% FOR THE USE OF THIS SOFTWARE.  If software is modified to produce
+% derivative works, such modified software should be clearly marked.
+% Additionally, 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 the Free Software Foundation; version 2.0 of the License. 
+% Accordingly, this program is distributed in the hope that it will be 
+% useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
+% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
+% General Public License for more details.
+%
+% For function details and reference information, see:
+% http://www.sfu.ca/~ssurjano/
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% INPUT:
+%
+% xx = [x1, x2]
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+x1 = xx(1);
+x2 = xx(2);
+
+maxarg = max([0, x2-1/20]);
+
+yh1 = curretal88exp([x1+1/20, x2+1/20]);
+yh2 = curretal88exp([x1+1/20, maxarg]);
+yh3 = curretal88exp([x1-1/20, x2+1/20]);
+yh4 = curretal88exp([x1-1/20, maxarg]);
+
+y = (yh1 + yh2 + yh3 + yh4) / 4;
+
+end

docs/scripts/matlab/park91a.m

@@ -0,0 +1,50 @@
+function [y] = park91a(xx)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% PARK (1991) FUNCTION 1
+%
+% Authors: Sonja Surjanovic, Simon Fraser University
+%          Derek Bingham, Simon Fraser University
+% Questions/Comments: Please email Derek Bingham at [email protected].
+%
+% Copyright 2013. Derek Bingham, Simon Fraser University.
+%
+% THERE IS NO WARRANTY, EXPRESS OR IMPLIED. WE DO NOT ASSUME ANY LIABILITY
+% FOR THE USE OF THIS SOFTWARE.  If software is modified to produce
+% derivative works, such modified software should be clearly marked.
+% Additionally, 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 the Free Software Foundation; version 2.0 of the License. 
+% Accordingly, this program is distributed in the hope that it will be 
+% useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
+% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
+% General Public License for more details.
+%
+% For function details and reference information, see:
+% http://www.sfu.ca/~ssurjano/
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% INPUT:
+%
+% xx = [x1, x2, x3, x4]
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+x1 = xx(1);
+x2 = xx(2);
+x3 = xx(3);
+x4 = xx(4);
+
+term1a = x1 / 2;
+term1b = sqrt(1 + (x2+x3^2)*x4/(x1^2)) - 1;
+term1 = term1a * term1b;
+
+term2a = x1 + 3*x4;
+term2b = exp(1 + sin(x3));
+term2 = term2a * term2b;
+
+y = term1 + term2;
+
+end

docs/scripts/matlab/park91alc.m

@@ -0,0 +1,50 @@
+function [y] = park91alc(xx)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% PARK (1991) FUNCTION 1, LOWER FIDELITY CODE
+% Calls: park91a.m
+% This function, from Xiong et al. (2013), is used as the "low-accuracy
+% code" version of the function park91a.m.
+%
+% Authors: Sonja Surjanovic, Simon Fraser University
+%          Derek Bingham, Simon Fraser University
+% Questions/Comments: Please email Derek Bingham at [email protected].
+%
+% Copyright 2013. Derek Bingham, Simon Fraser University.
+%
+% THERE IS NO WARRANTY, EXPRESS OR IMPLIED. WE DO NOT ASSUME ANY LIABILITY
+% FOR THE USE OF THIS SOFTWARE.  If software is modified to produce
+% derivative works, such modified software should be clearly marked.
+% Additionally, 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 the Free Software Foundation; version 2.0 of the License. 
+% Accordingly, this program is distributed in the hope that it will be 
+% useful, but WITHOUT ANY WARRANTY; without even the implied warranty 
+% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
+% General Public License for more details.
+%
+% For function details and reference information, see:
+% http://www.sfu.ca/~ssurjano/
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% INPUT:
+%
+% xx = [x1, x2, x3, x4]
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+x1 = xx(1);
+x2 = xx(2);
+x3 = xx(3);
+x4 = xx(4);
+
+yh = park91a(xx);
+
+term1 = (1+sin(x1)/10) * yh;
+term2 = -2*x1 + x2^2 + x3^2;
+
+y = term1 + term2 + 0.5;
+
+end