Calculus
========


Divergence and curl
--------------------

What is divergence?
  Divergence measures how much a vector field spreads out or converges at a point. It's a scalar quantity that describes the "source" or "sink" strength of the field.

  .. math::

    \nabla \cdot \mathbf{F} = \frac{\partial f_x}{\partial x} + \frac{\partial f_y}{\partial y} + \frac{\partial f_z}{\partial z}

  **Physical interpretation:**
  
  - Positive divergence: Field flows outward (source)
  - Negative divergence: Field flows inward (sink)
  - Zero divergence: No net outflow (incompressible flow)

  **Visualization of positive, zero, and negative divergence:**

  .. plot:: notebooks/plot_divergence_visualization.py
     :include-source: False

  The left panel shows positive divergence (source) for the vector field :math:`\mathbf{F} = (x, y)`, which has :math:`\nabla \cdot \mathbf{F} = +2`. Field lines radiate outward from the origin. The middle panel shows zero divergence for the rotational field :math:`\mathbf{F} = (-y, x)`, which has :math:`\nabla \cdot \mathbf{F} = 0`—this is an incompressible flow where fluid circulates without expansion or compression. The right panel shows negative divergence (sink) for :math:`\mathbf{F} = (-x, -y)`, which has :math:`\nabla \cdot \mathbf{F} = -2`. Field lines converge toward the origin.

  **How to calculate divergence:**

  For the positive divergence case :math:`\mathbf{F} = (x, y)`:

  .. math::

    \nabla \cdot \mathbf{F} = \frac{\partial F_x}{\partial x} + \frac{\partial F_y}{\partial y} = \frac{\partial (x)}{\partial x} + \frac{\partial (y)}{\partial y} = 1 + 1 = 2

  For the zero divergence case :math:`\mathbf{F} = (-y, x)`:

  .. math::

    \nabla \cdot \mathbf{F} = \frac{\partial F_x}{\partial x} + \frac{\partial F_y}{\partial y} = \frac{\partial (-y)}{\partial x} + \frac{\partial (x)}{\partial y} = 0 + 0 = 0

  For the negative divergence case :math:`\mathbf{F} = (-x, -y)`:

  .. math::

    \nabla \cdot \mathbf{F} = \frac{\partial F_x}{\partial x} + \frac{\partial F_y}{\partial y} = \frac{\partial (-x)}{\partial x} + \frac{\partial (-y)}{\partial y} = -1 + (-1) = -2

What is curl?
  Curl measures the rotation or circulation of a vector field. It's a vector quantity that describes how much and in what direction the field "swirls" around a point.

  .. math::

    \nabla \times \mathbf{F} = \begin{vmatrix}
    \mathbf{\hat{i}} & \mathbf{\hat{j}} & \mathbf{\hat{k}} \\
    \frac{\partial}{\partial x} & \frac{\partial}{\partial y} & \frac{\partial}{\partial z} \\
    f_x & f_y & f_z
    \end{vmatrix}

  .. math::

    = \mathbf{\hat{i}}\left(\frac{\partial f_z}{\partial y} - \frac{\partial f_y}{\partial z}\right) - \mathbf{\hat{j}}\left(\frac{\partial f_z}{\partial x} - \frac{\partial f_x}{\partial z}\right) + \mathbf{\hat{k}}\left(\frac{\partial f_y}{\partial x} - \frac{\partial f_x}{\partial y}\right)

  **Visualization of positive, zero, and negative curl:**

  .. plot:: notebooks/plot_curl_visualization.py
     :include-source: False

  The left panel shows positive curl (counterclockwise rotation) for the vector field :math:`\mathbf{F} = (-y, x)`, which has :math:`\nabla \times \mathbf{F} = +2`. The middle panel shows zero curl for the gradient field :math:`\mathbf{F} = (2x, 2y) = \nabla(x^2 + y^2)`, which has :math:`\nabla \times \mathbf{F} = 0`—this is a conservative field that can be integrated to give a scalar potential. The right panel shows negative curl (clockwise rotation) for :math:`\mathbf{F} = (y, -x)`, which has :math:`\nabla \times \mathbf{F} = -2`.

  **How to calculate curl in 2D:**

  In 2D, we only need the z-component of curl (the component pointing out of the page):

  .. math::

    (\nabla \times \mathbf{F})_z = \frac{\partial F_y}{\partial x} - \frac{\partial F_x}{\partial y}

  For the positive curl case :math:`\mathbf{F} = (-y, x)`:

  .. math::

    (\nabla \times \mathbf{F})_z = \frac{\partial (x)}{\partial x} - \frac{\partial (-y)}{\partial y} = 1 - (-1) = 1 + 1 = 2

  For the zero curl case :math:`\mathbf{F} = (2x, 2y)`:

  .. math::

    (\nabla \times \mathbf{F})_z = \frac{\partial (2y)}{\partial x} - \frac{\partial (2x)}{\partial y} = 0 - 0 = 0

  For the negative curl case :math:`\mathbf{F} = (y, -x)`:

  .. math::

    (\nabla \times \mathbf{F})_z = \frac{\partial (-x)}{\partial x} - \frac{\partial (y)}{\partial y} = -1 - 1 = -2

What does "conservative field" mean?
  A **conservative field** is a vector field that can be written as the gradient of a scalar function (potential). If :math:`\mathbf{F} = \nabla \phi` for some scalar :math:`\phi`, then the field is conservative.

  **Key property:** The curl of any gradient is zero:

  .. math::

    \nabla \times (\nabla \phi) = \mathbf{0}

  This works both ways:
  
  - **Forward**: If you have a scalar function :math:`\phi(x,y)`, its gradient :math:`\nabla \phi = (\partial \phi/\partial x, \partial \phi/\partial y)` gives you a vector field with zero curl
  - **Backward (integration)**: If you have a vector field with zero curl, you can integrate it to find the original scalar function :math:`\phi`

  **Example from the middle panel:**
  
  - Start with scalar: :math:`\phi(x,y) = x^2 + y^2`
  - Take gradient: :math:`\nabla \phi = (2x, 2y)` — this is the vector field (arrows pointing outward)
  - Check curl: :math:`\nabla \times (2x, 2y) = \partial(2y)/\partial x - \partial(2x)/\partial y = 0 - 0 = 0` ✓

  **Why "conservative"?** The term comes from physics—specifically from the conservation of mechanical energy. When a force field is conservative, the total mechanical energy (kinetic + potential) remains constant as you move through the field.

  **The physics origin:**

  When you move an object through a force field :math:`\mathbf{F}` from point A to point B, the work done is:

  .. math::

    W = \int_A^B \mathbf{F} \cdot d\mathbf{r}

  For a conservative field where :math:`\mathbf{F} = -\nabla U` (force is negative gradient of potential energy :math:`U`):

  .. math::

    W = \int_A^B (-\nabla U) \cdot d\mathbf{r} = -(U_B - U_A) = U_A - U_B

  The work depends only on the start and end points, not on the path taken. This means:

  1. **Closed path work is zero**: If you return to your starting point (A = B), then :math:`W = U_A - U_A = 0`. No net energy is gained or lost going around a loop.
  2. **Energy is conserved**: The work done by the force equals the decrease in potential energy, so :math:`E_{\text{kinetic}} + U = \text{constant}`.
  3. **Path independence**: You can take any route from A to B and do the same amount of work.

  **Examples of conservative forces:**

  - **Gravity**: :math:`\mathbf{F} = -mg\mathbf{\hat{z}}`, potential :math:`U = mgz`. Lifting an object 10 meters requires the same energy whether you go straight up or spiral around.
  - **Electrostatic**: :math:`\mathbf{F} = k\frac{q_1 q_2}{r^2}\mathbf{\hat{r}}`, potential :math:`U = k\frac{q_1 q_2}{r}`. Moving a charge in an electric field conserves energy.
  - **Spring force**: :math:`\mathbf{F} = -kx\mathbf{\hat{x}}`, potential :math:`U = \frac{1}{2}kx^2`. Compressing a spring stores energy that can be fully recovered.

  **Non-conservative forces:**

  - **Friction**: Sliding an object around a loop dissipates energy as heat. The work depends on path length, not just endpoints. Cannot be written as :math:`\mathbf{F} = -\nabla U`.
  - **Magnetic force**: :math:`\mathbf{F} = q\mathbf{v} \times \mathbf{B}`. Always perpendicular to motion, does zero work, but still has curl (circulation around magnetic field lines).

Why curl = 0 for conservative fields?
  If :math:`\mathbf{F} = -\nabla U`, then by the vector calculus identity :math:`\nabla \times (\nabla U) = \mathbf{0}`, the curl must be zero. Physically, curl represents circulation or rotation in the field. If there's circulation, you can extract energy by going around a loop (like a water wheel in a vortex), violating energy conservation.

  **Connection to DPC:** When you measure center of mass shifts :math:`(g_x, g_y)` in DPC, you're measuring the gradient of the phase :math:`\nabla \phi`. If curl is zero, you can integrate :math:`g_x` and :math:`g_y` to recover the original phase :math:`\phi(x,y)`. If curl is non-zero, the field is not conservative and integration gives inconsistent results (you can't find a single-valued :math:`\phi`).

Why is curl important in DPC?
  In Differential Phase Contrast (DPC) microscopy, we measure the center of mass shift vector field :math:`\mathbf{g}(r_x, r_y) = (\text{com}_x, \text{com}_y)`. This vector field should ideally be the gradient of a scalar phase:

  .. math::

    \mathbf{g} = \nabla \phi = \left(\frac{\partial \phi}{\partial x}, \frac{\partial \phi}{\partial y}\right)

  **In the ideal case, the curl is zero:**

  .. math::

    \nabla \times \mathbf{g} = \frac{\partial g_y}{\partial x} - \frac{\partial g_x}{\partial y} \approx 0

  This is because **the curl of a gradient is always zero:**

  .. math::

    \nabla \times (\nabla f) = \mathbf{0}

  This is a fundamental vector calculus identity: the curl of any conservative vector field (one that can be written as the gradient of a function) is zero.

What does it mean when curl is not zero in DPC?
  When :math:`\nabla \times \mathbf{g} \neq 0`, the measured center of mass field is **not conservative**—it cannot be perfectly integrated to give a single-valued phase. This happens due to:

  - **Measurement noise**: Random errors in center of mass detection
  - **Sample rotation**: Physical misalignment between scan and detector coordinates
  - **Non-ideal imaging conditions**: Aberrations, multiple scattering

  Software like Ophus computes the curl and finds the optimal rotation angle where :math:`\nabla \times \mathbf{g}` becomes minimized. This aligns the coordinate systems and removes systematic errors before phase integration.

What is the phase from electrostatic potential?
  The phase shift acquired by an electron passing through an electrostatic potential :math:`V(x,y,z)` is:

  .. math::

    \phi(x,y) = \sigma \int V(x,y,z)\,dz

  where :math:`\sigma` is the interaction constant. This is the real-space reconstructed phase image that relates to the sample's potential.

  **"Phase contrast"** means large :math:`\phi` corresponds to regions with stronger potential (higher atomic number :math:`Z` or greater thickness).

Properties of divergence and curl summary
  **Key identities:**

  - :math:`\nabla \times (\nabla f) = \mathbf{0}` — curl of a gradient is zero
  - :math:`\nabla \cdot (\nabla \times \mathbf{F}) = 0` — divergence of a curl is zero
  - If :math:`\nabla \times \mathbf{F} = \mathbf{0}` everywhere, then :math:`\mathbf{F} = \nabla \phi` for some scalar :math:`\phi` (conservative field)

  These identities are fundamental to understanding why DPC works: we measure gradients (center of mass shifts) and integrate them back to get phase, but this only works perfectly when curl is zero.