Fix input files documentation

input/equil_a.txt

@@ -1,4 +1,4 @@
  : rr0m,zr0m,rpam  ! rhot[m] = min(sqrt((r-rr0m)**2+(z-zr0m)**2), rpam); tor flux phi = pi*b0*rhot**2
  : b0              ! Bphi[T] @ rr0m[m]
- : q0,qa,alq       ! q = q0 + (qa-q0)*sqrt(psin)**alq
+ : q0,qa,alq       ! q = q0 + (qa-q0)*rhot**alq
  : nlim            ! number of points in first wall (rlim,zlim) polygon

src/beams.f90

@@ -12,15 +12,16 @@ contains
     !
     !   1 f
     !   2 x₀ y₀ z₀
-    !   3 w₁ w₂ z₁ z₂ φ
+    !   3 w₀₁ w₀₂ d₀₁ d₀₂ φ
     !
     ! where:
     !   - f is the frequency (GHz)
-    !   - x₀, y₀, z₀ are the launcher position (mm)
+    !   - x₀, y₀, z₀ are the launcher position (cm)
-    !   - w₁,w₂ are the beam waists in the two principal directions (mm)
+    !   - w₀₁,w₀₂ are the beam waists in the two principal directions (cm)
-    !   - z₁,z₂ are the positions of the foci in the two principal
+    !   - d₀₁,d₀₂ are the distances of the beam waists from the launch
-    !     directions (mm)
+    !     point (cm)
-    !   - φ is the of the ellipse (deg)
+    !   - φ is the rotation angle from the horizontal direction to the
+    !     first principal direction (deg)
     !
     ! Note: this case implies simple astigmatism, i.e. the
     ! amplitude and phase ellipses in the transverse plane
@@ -40,7 +41,7 @@ contains
 
     ! local variables
     integer :: u
-    real(wp_) :: k0, w0(2), z0(2), z_R(2), phi
+    real(wp_) :: k0, w0(2), d0(2), z_R(2), phi
 
     u = get_free_unit(unit)
 
@@ -54,8 +55,9 @@ contains
     read(u, *) params%fghz  ! Wave frequency (GHz)
     read(u, *) params%pos   ! Launcher position (Cartesian coordinates)
     read(u, *) w0, &        ! Beam waists (in the ξ,η axes)
-               z0, &        ! Foci positions (in the ξ,η axes)
+               d0, &        ! Waists (along ξ,η axes) distance from launcher
-               phi          ! Ellipse axes angle
+               phi          ! rotation angle from horizontal direction to
+                            ! ξ axis in the transverse plane
     close(u)
 
     ! Wavevector k₀
@@ -67,11 +69,11 @@ contains
 
     ! Beam widths in the ξ, η directions at z=0:
     ! w² = w₀² (1 + z₀²/z_R²)
-    params%w = w0 * sqrt(1 + (z0/z_R)**2)
+    params%w = w0 * sqrt(1 + (d0/z_R)**2)
 
     ! Curvature in the ξ, η directions at z=0:
     ! K = 1/R = (z-z₀)/[(z-z₀)² + z_R²]
-    params%ri = -z0 / (z0**2 + z_R**2)
+    params%ri = -d0 / (d0**2 + z_R**2)
 
     ! Ellipse axes angle
     params%phi = phi
@@ -88,13 +90,14 @@ contains
     !   2. The rest of file is a table with the following columns:
     !        θ, α, β, x₀, y₀, z₀, w₁, w₂, k₁, k₂, φ_w, φ_R
     !   3 The meaning of the columns is
-    !     - θ is the mechanical steering angle (useless)
+    !     - θ is the mechanical steering angle (unused)
     !     - α, β are the poloidal and toroidal launch angles (deg)
     !     - x₀, y₀, z₀ are the launcher position (mm)
-    !     - w₁,w₂ are the beam waists in the two principal directions (mm)
+    !     - w₁,w₂ are the beam widths in the two principal directions (mm)
     !     - k₁,k₂ are the wavefront curvatures in the two principal
     !       directions (mm⁻¹)
-    !     - φ_w, φ_R are the angles of the amplitude and phase ellipses (deg)
+    !     - φ_w, φ_R are the rotation angles of the amplitude and phase
+    !       ellipses in the transverse plane at the launch point (deg)
 
     use gray_params,  only : antenna_parameters
     use splines,      only : spline_simple
@@ -214,6 +217,43 @@ contains
   subroutine read_beam2(params, beamid, err, unit)
     ! Reads the wave launcher parameters for the general case
     ! where w(z, α, β) and 1/R(z, α, β) depend on the launcher angles α, β.
+    !
+    ! Format notes:
+    !   1. The first line contains the number N of beams defined in the file
+    !   2. The following N lines contain the following data for each of the
+    !      N beams:
+    !        ID,iox,f,na,nb
+    !   3. The meaning of the data is
+    !      - ID is a label to identify the beam
+    !      - iox=1,2 is a flag to select O-mode (1) or X-mode (2) polarization
+    !      - f is the wave frequency (GHz)
+    !      - n*m is the number of rows of the corresponding table below with
+    !        the beam parameters.
+    !        * If the beam steering is fixed: na=nb=1
+    !        * For a steering around a single axis:
+    !          na>1 and nb=1, or na=1 and nb>1.
+    !        * For a steering with two independent axes:
+    !          n>1 and m>1.
+    !        The row number l of the following table is mapped to two indexes
+    !        i,j (1≤i≤na, 1≤j≤nb) via l=i+na*(j-1), i.e., the index i "runs
+    !        faster".
+    !        Index i is assumed to be associated to a steering mainly in the
+    !        poloidal direction and the poloidal launch angle α(i,j) must be
+    !        monotonous along its first dimension.
+    !        Index j is assumed to be associated to a steering mainly in the
+    !        toroidal direction and the toroidal launch angle β(i,j) must be
+    !        monotonous along its second dimension.
+    !   4. The rest of file is a sequence of N tables with the following
+    !      columns:
+    !        α, β, x₀, y₀, z₀, w₁, w₂, k₁, k₂, φ_w, φ_R
+    !   5. The meaning of the columns is
+    !     - α, β are the poloidal and toroidal launch angles (deg)
+    !     - x₀, y₀, z₀ are the launcher position (mm)
+    !     - w₁,w₂ are the beam widths in the two principal directions (mm)
+    !     - k₁,k₂ are the wavefront curvatures in the two principal
+    !       directions (mm⁻¹)
+    !     - φ_w, φ_R are the rotation angles of the amplitude and phase
+    !       ellipses in the transverse plane at the launch point (deg)
 
     use gray_params, only : antenna_parameters
     use utils,       only : get_free_unit, intlin, locate