Project template
================

The two folders beside this file are the model every project follows. Copy the
structure, rename everything after your own project, and replace the contents.
They solve the same physics problem twice -- once exactly on paper, once on a
grid -- which is worth reading side by side before you start your own.

What a project folder contains
------------------------------
  <Project>.tex      The report, named after the folder. A self-contained LaTeX
                     article: it compiles to a PDF on its own, and the course
                     website builder renders the same file into a web page.

  code/              Everything you wrote.
    make_figures.py    Produces every PNG and GIF, writing them to ../figures/.

  figures/           Only generated output -- never edit these by hand.
    fig_*.png          The static figures the report includes.
    anim.gif           The animation shown on the website and used as the
                       moving preview on the projects page.
    anim_poster.png    One still frame of it, shown in the PDF instead.

Nothing else belongs in the folder. LaTeX leaves .aux, .log, .out and
.synctex.gz behind when it runs -- delete them before you hand the project in.
So are notebooks, exported HTML, __pycache__, and second copies of a figure
with "_1" in the name.

How to build it
---------------
  cd code
  python make_figures.py      # rewrites everything in ../figures/
  cd ..
  pdflatex <Project>.tex      # check the PDF still compiles

Requirements: numpy, matplotlib, scipy, pillow, and a LaTeX installation.

No code in the report
---------------------
The report is for the physics and the mathematics. Do not paste source listings
into it. Describe what the program does and what choices matter -- the grid, the
step size, the checks you ran -- and let the figures carry the results. The code
itself lives in code/, where a reader who wants it can read it properly.

Say where the course shows up
-----------------------------
Name the idea and the chapter at the point where you use it, not only in a list
at the end:

    "Separating the time dependence (Chapter 2) turns the time-dependent
     Schrodinger equation into an eigenvalue problem for H."

    "The kinetic operator is diagonal in the momentum representation
     (Chapter 1), which is what makes each step of the split-step method cheap."

    "Unitarity (Chapter 1) is the check: the norm holds to 1e-12 over the run."

Half the point of the project is recognising this course inside a problem it
was not written for. A reader should be able to see where every step came from.

What the website needs
----------------------
All of these are defined in the preamble of each example so the file still
compiles on its own. Do not rename them or reorder their arguments.

The first three open the report, in this order -- the problem comes before
anything you wrote about it:

  \projectinfo{Title}{Your name}{One- or two-sentence abstract}
      Prints the title and your name, and sets the heading of the web page and
      the card on the projects list. It holds the abstract back until
      \projectabstract asks for it.

  \begin{problemstatement} ... \end{problemstatement}
      The question you set out to answer, written out as a problem: the given
      data, and what is to be found, in parts. Put it immediately after
      \projectinfo, before any section of your own. It is set apart at the top
      of the page, so a reader knows what was asked before reading how you
      answered it. Write it as a problem, not as a summary -- if someone could
      be handed just this block and start work, it is right.

  \projectabstract
      Prints the abstract from \projectinfo. It goes directly under the problem
      block, where your report begins.

  \projectmethod{analytic}   or   \projectmethod{numerical}
      How you solved it. Put it just after \begin{document}. It prints nothing
      in the PDF -- your report says which it is in its own words -- but the
      website files your project under that heading. "analytic" means closed
      form; if one step of it has no closed form and you evaluated an integral
      or summed a series numerically, it is still analytic, and your report
      should say which step and why.

And in the body of the report:

  \webanimation{figures/anim.gif}{figures/anim_poster.png}{Caption}
      Shows the animated GIF on the website and the still frame in the PDF.

Figure paths must point inside figures/, e.g.
\includegraphics[width=0.95\linewidth]{figures/fig_fields.png}

What makes a good project
-------------------------
  [ ] A title that names the physics and the method.
  [ ] The problem stated at the top, in problemstatement, as a problem someone
      else could be set: what is given, and what is to be found.
  [ ] The physics question stated clearly, in a way a reader one course behind
      you would follow.
  [ ] The mathematics worked out -- real steps, not just the final formula.
  [ ] The course named where it is used: chapter by chapter, in place.
  [ ] Python that actually produces the data and the figures.
  [ ] At least one animation. It is what makes someone open your project: the
      projects page shows it as the preview, so make it the best thing you make.
  [ ] A caption on the animation that says what to watch for.
  [ ] A check on the result: a conservation law, a limit, a known formula. In
      quantum mechanics the cheapest ones are the norm, the orthogonality of
      two states that should be orthogonal, and a limit where the answer is
      already known (a wide barrier, a small field, a large quantum number).
  [ ] The report compiles and every figure it references exists.

On the figures
--------------
The figures are part of the argument, so they get the same care as the algebra.
Four rules the example projects follow:

  * A signed quantity (a wavefunction with a node, a field that is positive here
    and negative there) gets a diverging colour scale with a neutral tone at
    zero. A magnitude such as |psi|^2, which has no sign, gets one hue running
    light to dark. Never a rainbow such as 'jet': it bands a smooth field and
    gives zero no special status.
  * Two quantities with different units never share an axis. Use two panels. A
    probability density and a potential in the same picture need either two
    axes or an explicit statement of the scaling.
  * Set the type large. A figure that is readable on your laptop at full size
    is often unreadable in a report at half width or on a projector.
  * Label the thing itself where you can, rather than making the reader travel
    to a legend and back -- and put the label where it covers nothing.
