PHYS 3260 -- Project template
=============================

This folder is the model every project follows. Copy its structure, rename
everything after your own project, and replace the contents.

What a project folder contains
------------------------------
  Maxwell.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.

You also hand in a ten-minute presentation (see the checklist below). It is not
stored in this folder and is not published on the website; submit it separately.

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

Requirements: numpy, matplotlib, scipy, pillow, and a LaTeX installation. The
figures set their text with real LaTeX, so latex and dvipng must be on your PATH
-- that is what makes the symbols in the figures match the symbols in the report.

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 method and the chapter at the point where you use it, not only in a
list at the end:

    "Separating the variables (Chapter 10) turns one PDE in three variables
     into three ordinary differential equations."

    "The radial equation is Bessel's equation, solved by the Frobenius series
     of Chapter 9."

    "The inner product carries the polar Jacobian r (Chapter 5)."

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 which chapter every step came
from.

What the website needs
----------------------
All four are defined in the preamble of Maxwell.tex 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 a classmate
      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 classmate 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.
  [ ] The report compiles and every figure it references exists.
  [ ] A ten-minute presentation -- PowerPoint, Keynote or Beamer -- covering the
      question, the mathematics, the figures and the conclusion. Roughly one
      slide per minute. Put your equations in it as they appear in the report;
      if your tool cannot set mathematics well, screenshot them from your PDF.
      Hand it in separately from the project folder.

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 field that is positive here and negative there) gets a
    diverging colour scale with a neutral tone at zero. A magnitude, 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.
  * 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.
