Group Presentation

March 24, 2016

Jonas Kersulis

Using these slides

Hosted online

Controls:

Arrows/swiping Navigation
Home/End Goto first/last slide
Escape See slide overview

Goals

  1. Discuss project organization.
    • Where stuff goes
    • What to call it
  2. Show you some tools.
    • Free
    • Stable
    • Cross-platform

This is not

"Open-source rules, blah blah etc."

But you know where to find me. :)

Project /

/nb/ Notebooks
/src/ Source code
/data/ Data
/images/ Images
/papers/ Papers
/posters/ Posters
/present/ Presentations

Notebooks /nb/


nb/
    2016-02-03-change-line-data-input.ipynb
    2016-02-04-updating-figures.ipynb
    2016-02-05-normalized-performance-figure.ipynb
    2016-02-09-abstraction.ipynb
    2016-02-10-new-interface.md
    2016-02-18-clean-start.md
    2016-02-22-parametric-analysis.ipynb
    2016-02-22-translation-revisited.ipynb
    report-2016-01-19.ipynb
  • Each file is a Jupyter notebook.
    • Named by date.
    • Mixture of documentation and code.
  • Reports less frequent
    • Semi-formal summary of several notebooks.
    • Pieces often make it into papers.

Code /src/ 


src/
    TemporalInstanton.jl
    dataload.jl
    matrixbuilding.jl
    solvetmpinst.jl
    manipulations.jl
    thermalmodel.jl
    powerflow.jl
    plot.jl
  • Self-contained.
  • Version-controlled. (More on that later.)
  • Files below roughly 200 lines.

Data /data/

  • All data goes here: csv, txt, mat, jld, hdf5...
  • Independent from source code!
  • Plaintext > binary.

Images /images/

  • All generated figures go here.
  • A paper/poster has its own /images/.
  • Once an image is publication-quality, copy it to the individual paper/poster's folder.

Papers

/papers/

Posters

/posters/

Presentations

/present/
  • Each paper, poster, and presentation has its own directory.
  • Contents self-explanatory.
  • Keep images in their own sub-directory.

Demos

Jupyter Tool for interlacing code, code output, documentation, typeset math
TeXstudio LaTeX editing environment with drag-and-drop, autocomplete, bidirectional sync, and integrated PDF viewer
Atom Free text editor commissioned by GitHub
Git Version control software of choice for Linux kernel development, major tech companies, and ten million GitHub users

Jupyter

Tool for interlacing code, code output, and documentation (including typeset math)
  • My tool for keeping a lab notebook.
  • Stable, not mature (15 yrs for IPython, 2 for "Project Jupyter").

Getting started

Project homepage

Demo

  • Interface
  • Math + documentation + code
  • Language-agnostic
  • Export to PDF

Ecosystem

  • nbviewer: free notebook rendering and discovery service.
  • binder: Allow others to run your notebooks even if they don't have Jupyter installed!
    • Example: click here from any device to work through Raj's EECS 551 background subtraction demo.
  • Here's a recent post about the state of Jupyter's ecosystem.

TeXstudio

LaTeX editing environment with drag-and-drop, autocomplete, bidirectional sync, and integrated PDF viewer
  • Stable. Recent releases have been mostly bugfixes.

Getting started

Download

Demo

  • Interface
  • Macros
  • Autocomplete environments + references

Atom

Free text editor commissioned by GitHub
  • Written in HTML, CSS, and JavaScript.
  • Stable.
  • Widely used. Tons of packages available.

Getting started

Download

Demo

  • Search tags
  • Search commands
  • Multi-cursor

Git

Version control software of choice for Linux kernel development, major tech companies, ten million GitHub users...

  • Stable and mature.

Gitting started

Git philosophy

  • Every file and folder has a hash.
  • Every change you make has a hash.
  • Every project state has a hash.
  • .git holds all the hashes.
  • Restore any state, compare states, etc.

Why?

  • Say you
    • profile your code,
    • make changes for a month,
    • profile again.
  • Suppose your code performs worse after the changes.

    • If you recorded the git hash when you first profiled, you can use git diff to see a neat summary of all changes you made.

    You could also check out several code states to figure out which change caused the regression.

Caution

  • Learning curve
  • Overkill for small bits of code (use gists to publish tidbits).

Motivation

Jason Moore's dissertation

  • Website
  • PDF
  • Research code
  • Code to generate figures

A page from the website:

A page from the PDF:

What Jason wrote

Bonus: complete history of the project, start to finish.

Summary

Have a reason for

  • Where you put folders and files
  • What you call stuff

Try the one that sounds most useful:

  • Jupyter: notes and code development
  • TeXstudio: LaTeX editing
  • Atom: text editing
  • Git: version control