small fixes and cleanup (#6)

* small fixes and cleanup

* review

papers/kyle_sunden/wrightsim.rst

@@ -33,7 +33,7 @@
     different experimental setups.
     Simulations are accomplished through a Python interface that is designed
     to be intuitive for experimentalists and theorists.
-    We have worked to ensure that the numerical integration itself is performant.
+    We have worked to ensure that the numerical integration is performant.
     We report several algorithimic improvements that make ``WrightSim`` faster
     than previous implementations.
     The effect of parallelizing the simulation, both at the CPU and GPU
@@ -42,8 +42,8 @@
     ``WrightSim`` multiple orders of magnitude faster than previous
     implementations.
     ``WrightSim`` represents a large step forward towards the goal of a fast,
-    accurate, and easy to use general purpose simulation package for the
-    multidimensional spectroscopy commmunity.
+    accurate, and easy to use general purpose simulation package for
+    multidimensional spectroscopy.
     To our knowledge, ``WrightSim`` is the first openly licensed software package
     for these kinds of simulations.
     Potential further improvements are discussed.
@@ -84,9 +84,9 @@ We present a general-purpose simulation package for MDS: ``WrightSim`` [#]_.
     Simulated spectrum at normalized coordinates :label:`fig:examplespectrum`
 
 Figure :ref:`fig:examplespectrum` shows an example visualization of a
-spectrum in 2-Dimensional frequency space.
-The axes are two different frequencies for the input electric fields, the axes
-are normalized such that there is a resonance around :math:`0.0` in both
+spectrum in 2-dimensional frequency-frequency space.
+The axes are two different frequencies for two different input electric fields.
+The axes are normalized such that there is a resonance around :math:`0.0` in both
 frequencies.
 This system that we have chosen for this simulation is very simple, with a single
 resonance.
@@ -98,8 +98,9 @@ become an axis in the simulation.
 ``WrightSim`` is designed with the experimentalist in mind, allowing users
 to parameterize their simulations in much the same way that they would collect
 a similar spectrum in the laboratory.
-``WrightSim`` is modular and flexible---it is capable of simulating different
-kinds of MDS, and it is easy to extend to new kinds.
+``WrightSim`` is modular and flexible.
+It is capable of simulating different kinds of MDS, and it is easy to extend to
+new kinds.
 ``WrightSim`` uses a numerical integration approach that captures the full
 interaction between material and electric field without making common limiting
 assumptions.
@@ -119,17 +120,18 @@ shown itself to be a powerful tool.
 A Brief Introduction on Relevant Quantum Mechanics
 ==================================================
 
-If you are interested in a more full understanding, please refer to
-Kohler, Thompson, and Wright :cite:`Kohler_2017`. This
-introduction is intended to very quickly introduce *what* is being done,
+This introduction is intended to very quickly introduce *what* is being done,
 but not *why*.
+If you are interested in a more complete description, please refer to
+Kohler, Thompson, and Wright :cite:`Kohler_2017`.
+
 ``WrightSim`` uses the density matrix formulation of quantum mechanics.
 This formulation allows us to describe mixed states (coherences) which are key
 players in light-matter-interaction and spectroscopy.
-We propagate all of the relevant density matrix elements, including
-populations and coherences, in our numerical simulation.
 This strategy has been described before :cite:`Gelin_2009`, so we are brief in our
 description here.
+We propagate all of the relevant density matrix elements, including
+populations and coherences, in our numerical simulation.
 This places ``WrightSim`` at an intermediate level of theory, one where
 the mechanisms by which the desired signal arises are known, but have
 non-trivial spectral features as a result.
@@ -151,9 +153,6 @@ solid down arrow).
 Experimentalists isolate this condition spatially, by placing an aperature
 where this condition is met.
 This results in 16 possible pathways which result in a productive emission.
-For the purposes of this paper it is not necessary to fully understand what is
-meant by this diagram, the intent is simply to show the complexity of the
-problem at hand.
 Experimentalists can isolate the time orderings by introducing delays between
 pulses.
 Simulation allows us to fully separate each pathway, leading to insight into
@@ -185,8 +184,8 @@ already interacted. Interactions occur along the arrows, which generate
 density in the resulting state. Here, the fields must each interact exactly once.
 Output is generated by the rightmost two nodes, which have interacted with all
 three fields. These nine states represent all possible states which
-match the criterion described by the process we are simulating. We can
-take these nine states and collect them into a state density vector,
+match the criterion described by the process we are simulating.
+We take these nine states and collect them into a state density vector,
 :math:`\overline{\rho}` (Equation 1.1):
 
 .. math::
@@ -204,10 +203,11 @@ take these nine states and collect them into a state density vector,
    \tilde{\rho}_{21}^{(1-2+2^\prime)}
    \end{bmatrix}
 
-Next we need to quantitate the transitions within these states. This is the
-Hamiltonian matrix. Since we have nine states in our density vector, the
-Hamiltonian is a nine by nine matrix. To assist in representing the
-matrix, six time dependent variables are defined:
+Next we need to describe the transitions within these states.
+This is the Hamiltonian matrix.
+Since we have nine states in our density vector, the
+Hamiltonian is a nine by nine matrix.
+To simplify representation, six time dependent variables are defined:
 
 .. math::
 
@@ -243,43 +243,25 @@ These variables can then be used to populate the matrix:
    \end{bmatrix}
    \label{eq:single_Q}
 
-The :math:`\Gamma` values along the diagonal represent dephasing, that
-is, loss of coherence, which happens without any interaction. The
-:math:`\Gamma` for populations is the population decay rate. To isolate
-a given time ordering, we can simply set the value of elements which do
-not correspond to that time ordering to zero.
+The :math:`\Gamma` values along the diagonal represent loss terms such as
+depahsing (loss of coherence) and population relaxation.
+To isolate a given time ordering, we can simply set the value of elements which
+do not correspond to that time ordering to zero.
 
 At each time step, the dot product of the matrix with the
-:math:`\overline{\rho}` vector is the change in the
-:math:`\overline{\rho}` vector to the next time step (when multiplied by
-the differential). Both ``NISE`` and ``WrightSim`` use a more advanced,
-second order technique (Runge-Kutta) for determining the change in the
-:math:`\overline{\rho}` vector, but the idea is the same. The core of
-the simulations is to take the :math:`\overline{\rho}` vector and
+:math:`\overline{\rho}` vector is the change in the :math:`\overline{\rho}`
+vector to the next time step (when multiplied by the differential).
+``WrightSim`` uses a second order technique (Runge-Kutta) for determining the
+change in the :math:`\overline{\rho}` vector.
+The core of the simulations is to take the :math:`\overline{\rho}` vector and
 multiply by the Hamiltonian at each time step (noting that the
-Hamiltonian is time dependant, as are the electric fields, themselves). This process
-repeats over a large number of small time steps, and must be performed
+Hamiltonian is time dependant, as are the electric fields, themselves).
+This process repeats over a large number of small time steps, and must be performed
 separately for any change in the inputs (e.g. frequency [:math:`\omega`]
-or delay[:math:`\tau`]). As a result, the operation is ripe to be performed
-in parallel.
-
-``NISE``: Numerical Integration of the Shrödinger Equation
-==========================================================
-
-``NISE`` :cite:`nise` is the open-source package written by
-Kohler and Thompson while preparing their manuscript
-:cite:`Kohler_2017`. ``NISE`` uses a slight variation on the
-technique described above, whereby they place a restriction on the time
-ordering represented by the matrix, and can thus use a seven element
-state vector rather than a 9 element state vector. This approach is
-mathematically equivalent to that presented above. The approach
-presented is what is used in ``WrightSim``. The trade off is that to
-obtain a full picture, they must build in a mechanism to perform two
-simulations at the same time, increasing complexity, and actually
-reducing performance.
-
-``NISE`` is included here as a reference for the performance of previous
-simulations of this kind.
+or delay[:math:`\tau`]).
+As a result, the operation is highly parallelizable.
+The integration is performed in the rotating frame so the number of time steps
+can be as small as possible.
 
 Usage
 =====
@@ -293,16 +275,14 @@ The key steps to running a basic simulation are:
 - Run the scan
 - Process the results
 
-Experimental spaces are defined in an INI format that defines a set of parameters
-and specifies their defaults and relationships.
+Experimental spaces are defined in an INI format that defines a set of parameters and specifies their defaults and relationships.
+This can be thought of as a particular experimental setup or instrument.
 Here, we are using a space called ``trive`` which provides, among other settings,
 two independent frequency axes and two independent delay axes, controlling a total of
 three incident pulses.
 The frequency axes are called ``w1`` and ``w2`` [#]_, the delays are termed ``d1`` and ``d2``.
-To scan a particular axis, simply set the ``points`` array to a ``NumPy`` array and set it's ``active``
-attribute to ``True``.
-You can also set a static value for any available axis, by setting the ``points`` attribute to
-a single number (and keeping ``active`` set to ``False``).
+To scan a particular axis, simply set the ``points`` array to a ``NumPy`` array and set it's ``active`` attribute to ``True``.
+You can also set a static value for any available axis, by setting the ``points`` attribute to a single number (and keeping ``active`` set to ``False``).
 Finally, the ``experiment`` class tracks the timing in the simulation.
 Three main parameters control this: ``timestep``, which controls the size of each numerical integration step,
 ``early_buffer``, which defines how long to integrate before the first pulse maximum, and
@@ -380,18 +360,18 @@ The exception is the special string ``'gpu'``, which will cause ``WrightSim`` to
     # obtain results as a NumPy array
     gpuSig = scan.sig.copy()
 
-Running returns a ``Scan`` object, which allows for interrogation of several internal features of the scan
-including the electric field values themselves.
+Running returns a ``Scan`` object, which allows for interrogation of several
+internal features of the scan including the electric field values themselves.
 The important part, however is the signal array that is generated.
-In this example, the complex floating point number array is of shape :math:`(2x64x64x32)` (i.e. the number of
-``recorded_elements`` followed by the shape of the experiment itself).
-These numbers can be manipulated and visualized to produce spectra like that seen in :ref:`fig:examplespectrum`.
+In this example, the complex floating point number array is of shape
+:math:`(2x64x64x32)` (i.e. the number of ``recorded_elements`` followed by the
+shape of the experiment itself).
+These numbers can be manipulated and visualized to produce spectra like that
+seen in :ref:`fig:examplespectrum`.
 The Wright Group also maintains a library for working with multidimensional data, ``WrightTools``.
 This library will be integrated more fully to provide even easier access to visualization and
 archival storage of simulation results.
 
-
-
 Performance
 ===========
 
@@ -402,7 +382,14 @@ Another key is taking advantage of modern hardware for parallelization.
 These implementations have their advantages and tradeoffs, which are quantified and
 examined in detail herein.
 
-
+``NISE`` :cite:`nise` is the package written by Kohler and Thompson while
+preparing their manuscript :cite:`Kohler_2017`.
+``NISE`` uses a slight variation on the technique described above, whereby they
+place a restriction on the time ordering represented by the matrix, and can
+thus use a seven element state vector rather than a 9 element state vector.
+This approach is mathematically equivalent to that presented above.
+``NISE`` is included here as a reference for the performance of previous
+simulations of this kind.
 
 Algorithmic Improvements
 ------------------------
@@ -483,7 +470,7 @@ the Matrices prior to entering the loop. This was done to conserve
 memory on the GPU. Similarly, the electric fields are computed in the
 loop, rather than computing all ahead of time. These two optimizations
 reduce the memory overhead, and allow for easier to write functions,
-without the help of numpy do perform automatic broadcasting of shapes.
+without the help of NumPy do perform automatic broadcasting of shapes.
 
 Scaling Analysis
 ----------------