Add nperiods optional argument to add-near2far (#789)

doc/docs/Scheme_User_Interface.md

@@ -1145,9 +1145,9 @@ Note: in order for the far-field results to be accurate, the [far region must be
 
 There are three steps to using the near-to-far-field feature: first, define the "near" surface(s) as a set of surfaces capturing *all* outgoing radiation in the desired direction(s); second, run the simulation, typically with a pulsed source, to allow Meep to accumulate the Fourier transforms on the near surface(s); third, tell Meep to compute the far fields at any desired points (optionally saving the far fields from a grid of points to an HDF5 file). To define the near surfaces, use:
 
-**`(add-near2far fcen df nfreq near2far-regions...)`**
+**`(add-near2far fcen df nfreq near2far-regions... nperiods)`**
 —
-Add a bunch of `near2far-region`s to the current simulation (initializing the fields if they have not yet been initialized), telling Meep to accumulate the appropriate field Fourier transforms for `nfreq` equally-spaced frequencies covering the frequency range `fcen-df/2` to `fcen+df/2`. Return a `near2far` object, which you can pass to the functions below to get the far fields.
+Add a bunch of `near2far-region`s to the current simulation (initializing the fields if they have not yet been initialized), telling Meep to accumulate the appropriate field Fourier transforms for `nfreq` equally-spaced frequencies covering the frequency range `fcen-df/2` to `fcen+df/2`. Return a `near2far` object, which you can pass to the functions below to get the far fields. `nperiods` is a keyword argument that defaults to one, and can be passed after the list of `near2far-regions` like so: `(add-near2far fcen df nfreq region1 region2 region3 #:nperiods 2)`
 
 Each `near2far-region` is identical to `flux-region` except for the name: in 3d, these give a set of planes (**important:** all these "near surfaces" must lie in a single *homogeneous* material with *isotropic* ε and μ — and they should *not* lie in the PML regions) surrounding the source(s) of outgoing radiation that you want to capture and convert to a far field. Ideally, these should form a closed surface, but in practice it is sufficient for the `near2far-region`s to capture all of the radiation in the direction of the far-field points. **Important:** as for flux computations, each `near2far-region` should be assigned a `weight` of ±1 indicating the direction of the outward normal relative to the +coordinate direction. So, for example, if you have six regions defining the six faces of a cube, i.e. the faces in the +x, -x, +y, -y, +z, and -z directions, then they should have weights +1, -1, +1, -1, +1, and -1 respectively. Note that, neglecting discretization errors, all near-field surfaces that enclose the same outgoing fields are equivalent and will yield the same far fields with a discretization-induced difference that vanishes with increasing resolution etc.
 

scheme/meep.scm.in

@@ -520,7 +520,7 @@
   (define-property direction AUTOMATIC 'integer)
   (define-property weight 1.0 'cnumber))
 
-(define (fields-add-fluxish-stuff add-dft-stuff fields fcen df nfreq stufflist)
+(define (fields-add-fluxish-stuff add-dft-stuff fields fcen df nfreq stufflist . nperiods)
   (define vl '()) ; volume_list of flux regions
   (map (lambda (f)
 	 (let* ((v (volume (center (object-property-value f 'center))
@@ -540,7 +540,7 @@
        stufflist)
   (let ((stuff
 	 (add-dft-stuff fields vl
-			(- fcen (/ df 2)) (+ fcen (/ df 2)) nfreq)))
+			(- fcen (/ df 2)) (+ fcen (/ df 2)) nfreq (if (not (null? nperiods)) (car nperiods)))))
     (delete-meep-volume-list vl)
     stuff))
 
@@ -729,13 +729,16 @@
   (define-property direction AUTOMATIC 'integer)
   (define-property weight 1.0 'cnumber))
 
-(define (fields-add-near2far fields fcen df nfreq . near2fars)
+(define (fields-add-near2far fields fcen df nfreq nperiods . near2fars)
   (fields-add-fluxish-stuff meep-fields-add-dft-near2far
-			    fields fcen df nfreq near2fars))
+			    fields fcen df nfreq near2fars nperiods))
 
-(define (add-near2far fcen df nfreq . near2fars)
+(define* (add-near2far fcen df nfreq #:key (nperiods 1) . near2fars)
   (if (null? fields) (init-fields))
-  (apply fields-add-near2far (append (list fields fcen df nfreq) near2fars)))
+  ;; Keyword arguments automatically get added to the "rest" list in guile,
+  ;; so we have to remove the nperiods key and value from near2fars
+  (apply fields-add-near2far (append (list fields fcen df nfreq nperiods)
+                                     (delq #:nperiods (delq nperiods near2fars)))))
 
 (define (scale-near2far-fields s f)
   (meep-dft-near2far-scale-dfts f s))