Merge pull request #54 from fastalgorithms/docs

Docs

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt

chunkie/@chunker/chunker.m

@@ -1,8 +1,73 @@
 classdef chunker
-%CHUNKER class which describes a curve divided into chunks (panels). 
+%CHUNKER class which describes a curve divided into chunks (or "panels"). 
+%
 % On each chunk the curve is represented by the values of its position, 
-% first and second derivatives in parameter space on a Legendre grid.
+% first and second derivatives by scaled Legendre nodes.
+%
+% chunker properties:
+%   k - integer, number of Legendre nodes on each chunk
+%   nch - integer, number of chunks that make up the curve
+%   dim - integer, dimension of the ambient space in which the curve is 
+%             embedded
+%   npt - returns k*nch, the total number of points on the curve
+%   r - dim x k x nch array, r(:,i,j) gives the coordinates of the ith 
+%         node on the jth chunk of the chunker
+%   h - nch array of scaling factors for chunks. the chunk derivatives are
+%         scaled as if the coordinates in r(:,:,j) are sampled on an 
+%         interval of length 2*h(j). This affects integration formulas.
+%   d - dim x k x nch array, d(:,i,j) gives the time derivative of the 
+%         coordinate at the ith node on the jth chunk of the chunker
+%   d2 - dim x k x nch array, d(:,i,j) gives the 2nd time derivative of the 
+%         coordinate at the ith node on the jth chunk of the chunker
+%   n - dim x k x nch array of normals to the curve
+%   data - datadim x k x nch array of data attached to chunker points 
+%         this data will be refined along with the chunker
+%   adj - 2 x nch integer array. adj(1,j) is i.d. of the chunk that 
+%         precedes chunk j in parameter space. adj(2,j) is the i.d. of the
+%         chunk which follows. if adj(i,j) is 0 then that end of the chunk
+%         is a free end. if adj(i,j) is negative than that end of the chunk
+%         meets with other chunk ends in a vertex. the specific negative
+%         number acts as an i.d. of that vertex.
 %
+% chunker methods: 
+%   chunker(p,t,w) - construct an empty chunker with given preferences and
+%       precomputed Legendre nodes/weights (optional)
+%   obj = addchunk(obj,nchadd) - add nchadd chunks to the structure 
+%       (initialized with zeros)
+%   obj = makedatarows(obj,nrows) - add nrows rows to the data storage.
+%   [obj,info] = sort(obj) - sort the chunks so that adjacent chunks are
+%        stored sequentially
+%   [rn,dn,d2n,dist,tn,ichn] = nearest(obj,ref,ich,opts,u,xover,aover) -
+%        find nearest point on chunker to ref
+%   obj = reverse(obj) - reverse chunk orientation
+%   rmin = min(obj) - minimum of coordinate values
+%   rmax = max(obj) - maximum of coordinate values
+%   wts = weights(obj) - scaled integration weights on curve
+%   obj.n = normals(obj) - recompute normal vectors
+%   onesmat = onesmat(obj) - matrix that corresponds to integration of a
+%             density on the curve
+%   rnormonesmat = normonesmat(obj) - matrix that corresponds to
+%             integration of dot product of normal with vector density on
+%             the curve
+%   plot(obj,varargin) - plot the chunker curve
+%   plot3(obj,idata,varargin) - 3D plot of the curve and one row of the
+%             data storage
+%   quiver(obj,varargin) - quiver plot of the chnkr points and normals
+%   scatter(obj,varargin) - scatter plot of the chnkr nodes
+%   tau = taus(obj) - unit tangents to curve
+%   obj = refine(obj,varargin) - refine the curve
+%   a = area(obj) - for a closed curve, area inside 
+%   s = arclength(obj) - get values of arclength along curve
+%   kappa = signed_curvature(obj) - get signed curvature along curve
+%   rflag = datares(obj,opts) - check if data in data rows is resolved
+%   [rc,dc,d2c] = exps(obj) - get expansion coefficients for r,d,d2
+%   ier = checkadjinfo(obj) - checks that the adjacency info of the curve
+%              is consistent
+%   [inds,adjs,info] = sortinfo(obj) - attempts to sort the curve and finds
+%              number of connected components, etc
+%   [re,taue] = chunkends(obj,ich) - get the endpoints of chunks
+%   flag = flagnear(obj,pts,opts) - flag points near the boundary
+
 
 % author: Travis Askham ([email protected])
 
@@ -49,6 +114,16 @@
 
     methods
         function obj = chunker(p,t,w)
+        %CHUNKER construct an empty chunker with some default settings
+        %
+        % syntax: chnkr = chunker(p,t,w);
+        %
+        % optional input: 
+        %   p - struct of preferences 
+        %        p.k - integer, order to be used on chunks (16)
+        %        p.dim - integer, dimension of ambient space (2)
+        %   t, w - arrays of Legendre nodes and weights of order p.k
+        % 
             if nargin < 1 || isempty(p)
                 p = chunkerpref();
             else

chunkie/chunkerfunc.m

@@ -13,7 +13,7 @@
 %               [r,d] = fcurve(t);  or [r,d,d2] = fcurve(t);
 %            where d is the first derivative of r with respect to t and 
 %            d2 is the second derivative. in some situations, this will
-%            improve the convergence order. 
+%            improve the convergence order and final precision.
 %
 % Optional input:
 %	cparams - curve parameters structure (defaults)
@@ -25,9 +25,8 @@
 %           ifclosed == 0 (Inf)
 %       cparams.nover = oversample resolved curve nover
 %           times (0)
-%       cparams.eps = resolve coordinates, arclength,
-%          and first and second derivs of coordinates
-%          to this tolerance (1.0e-6)
+%       cparams.eps = tolerance to resolve coordinates and arclength 
+%           density (1.0e-6)
 %       cparams.lvlr = string, determines type of level
 %          restriction to be enforced
 %               lvlr = 'a' -> no chunk should have double the arc length 
@@ -42,6 +41,9 @@
 %       pref.nchmax - maximum number of chunks (10000)
 %       pref.k - number of Legendre nodes on chunks (16)
 %
+% Output:
+%   chnkr - a chunker object containing the discretization of the domain
+%
 % Examples:
 %   chnkr = chunkerfunc(@(t) starfish(t)); % chunk up starfish w/ standard
 %                                        % options

chunkie/demo/addpaths_loc.m

@@ -2,4 +2,4 @@ function addpaths_loc()
 
 addpath('../');
 addpath(genpath('../FLAM'));
-addpath('../fmm2d/matlab/')
+addpath('../fmm2d/matlab/');

chunkie/demo/demo_scatter.m

@@ -11,7 +11,7 @@
 
 % planewave vec
 
-kvec = 20*[1;-1.5];
+kvec = 10*[1;-1.5];
 
 %
 
@@ -101,42 +101,46 @@
 
 figure(2)
 clf
-subplot(1,3,1)
+
+t = tiledlayout(1,3,'TileSpacing','compact');
+
+nexttile
 zztarg = nan(size(xxtarg));
 zztarg(out) = uin;
 h=pcolor(xxtarg,yytarg,imag(zztarg));
 set(h,'EdgeColor','none')
+clim([-maxu,maxu])
+colormap(brewermap([],'RdBu'));
 hold on
-plot(chnkr,'LineWidth',2)
-axis equal
-axis tight
-colormap(redblue)
-caxis([-maxu,maxu])
-title('$u_{in}$','Interpreter','latex','FontSize',24)
-
+plot(chnkr,'k','LineWidth',2)
+axis equal tight
+set(gca, "box","off","Xtick",[],"Ytick",[]);
+title('$u^{\textrm{inc}}$','Interpreter','latex','FontSize',12)
 
-subplot(1,3,2)
+nexttile
 zztarg = nan(size(xxtarg));
 zztarg(out) = uscat;
 h=pcolor(xxtarg,yytarg,imag(zztarg));
 set(h,'EdgeColor','none')
+clim([-maxu,maxu])
+colormap(brewermap([],'RdBu'));
 hold on
-plot(chnkr,'LineWidth',2)
-axis equal
-axis tight
-colormap(redblue)
-caxis([-maxu,maxu])
-title('$u_{scat}$','Interpreter','latex','FontSize',24)
+plot(chnkr,'k','LineWidth',2)
+axis equal tight
+set(gca, "box","off","Xtick",[],"Ytick",[]);
+
+title('$u^{\textrm{scat}}$','Interpreter','latex','FontSize',12)
 
-subplot(1,3,3)
+nexttile
 zztarg = nan(size(xxtarg));
 zztarg(out) = utot;
 h=pcolor(xxtarg,yytarg,imag(zztarg));
 set(h,'EdgeColor','none')
+clim([-maxu,maxu])
+colormap(brewermap([],'RdBu'));
 hold on
-plot(chnkr,'LineWidth',2)
-axis equal
-axis tight
-colormap(redblue)
-caxis([-maxu,maxu])
-title('$u_{tot}$','Interpreter','latex','FontSize',24)
+plot(chnkr,'k','LineWidth',2)
+axis equal tight
+set(gca, "box","off","Xtick",[],"Ytick",[]);
+
+title('$u^{\textrm{tot}}$','Interpreter','latex','FontSize',12)

chunkie/guide/addpaths_loc.m

@@ -0,0 +1,4 @@
+function addpaths_loc()
+
+addpath('../');
+addpath(genpath('../FLAM'));

chunkie/guide/guide_chunkers.m

@@ -0,0 +1,129 @@
+%GUIDE_CHUNKERS
+%
+% This script complements the chunkie guide section on chunker objects.
+% It shows the most common methods for building and working with chunkers.
+%
+
+addpaths_loc();
+rng(1234);
+
+%%%%%%%%%%%%% circle
+% START CIRCLE
+% chunk up circle
+
+rad = 2; ctr = [1.0;-0.5];
+circfun = @(t) ctr + rad*[cos(t(:).');sin(t(:).')];
+
+chnkr1 = chunkerfunc(circfun);
+
+% plot curve, nodes, and normals
+
+figure(1)
+clf
+plot(chnkr1,'b-x')
+hold on
+quiver(chnkr1,'r')
+axis equal tight
+% END CIRCLE
+
+saveas(figure(1),"guide_chunkers_circle.png");
+
+%%%%%%%%%%%%% more examples 
+% START MORE PARAMS
+% curvebymode lets you specify a star shaped domain by 
+% a cosine/sine series for the radius
+
+modes = randn(11,1); modes(1) = 1.1*sum(abs(modes(2:end))); 
+ctr = [1.0;-0.5];
+chnkr2 = chunkerfunc(@(t) chnk.curves.bymode(t,modes,ctr));
+
+figure(2)
+clf
+plot(chnkr2,'b-x')
+hold on
+quiver(chnkr2,'r')
+axis equal tight
+
+% classic starfish domain
+
+narms = 5; 
+amp = 0.5;
+chnkr3 = chunkerfunc(@(t) starfish(t,narms,amp));
+
+figure(3)
+clf
+plot(chnkr3,'b-x')
+hold on
+quiver(chnkr3,'r')
+axis equal tight
+% END MORE PARAMS
+
+saveas(figure(2),"guide_chunkers_bymode.png");
+saveas(figure(3),"guide_chunkers_starfish.png");
+
+%%%%%%%%%%%%% rounded polygons
+% START ROUNDED POLY
+% roundedpolygon provides a chunk discretization of a rounded polygon
+
+verts = chnk.demo.barbell(2.0,2.0,1.0,1.0); % vertices of a barbell
+chnkr4 = roundedpolygon(verts);
+
+figure(4)
+clf
+plot(chnkr4,'b-x')
+hold on
+quiver(chnkr4,'r')
+axis equal tight
+% END ROUNDED POLY
+
+saveas(figure(4),"guide_chunkers_barbell.png");
+
+%%%%%%%%%%%%%% working with chunkers
+
+% START SHIFT AND REVERSE
+% make a copy of the random mode domain
+chnkr5 = chnkr2;
+
+% rotate it
+theta = pi/4; c = cos(theta); s = sin(theta); U = [c -s; s c];
+chnkr5.r(:,:) = U*chnkr5.r(:,:); % rotating affects position and derivatives
+chnkr5.d(:,:) = U*chnkr5.d(:,:);
+chnkr5.d2(:,:) = U*chnkr5.d2(:,:);
+
+% make a copy of the circle domain and shift it 
+chnkr6 = chnkr1;
+chnkr6.r = chnkr6.r + [-0.3;0.4]; % shifting only affects position
+% reverse the orientation
+chnkr6 = chnkr6.reverse();
+
+% merge these two curves into one domain
+chnkr7 = merge([chnkr5,chnkr6]);
+
+figure(5); clf
+plot(chnkr7,'b-x'); hold on; quiver(chnkr7,'r')
+axis equal tight
+% END SHIFT AND REVERSE
+
+saveas(figure(5),"guide_chunkers_shiftandreverse.png");
+
+% START INTERIOR
+
+% create a grid of points 
+mins = min(chnkr7); maxs = max(chnkr7);
+x1 = linspace(mins(1),maxs(1)); y1 = linspace(mins(2),maxs(2));
+[xx,yy] = meshgrid(x1,y1);
+pts = [xx(:).'; yy(:).'];
+
+% find the points inside the merged domain
+in = chunkerinterior(chnkr7,pts);
+
+zz = nan(size(xx));
+zz(in) = 1;
+
+figure(6)
+h = pcolor(xx,yy,zz); set(h,'EdgeColor','none');
+axis equal tight
+% END INTERIOR
+
+saveas(figure(6),"guide_chunkers_interior.png");
+