jbernhard · September 15, 2015 13:54 · Sep 15, 2015 · Sep 15, 2015
diff --git a/oscar2013.md b/oscar2013.md
@@ -0,0 +1,116 @@
+# OSCAR 2013
+
+This document specifies new formats for
+
+  * hydro full evolution
+  * hydro hypersurfaces
+  * particle evolution
+
+These formats aim to be as simple and flexible as possible while still containing all necessary information.  Ideally,
+existing files should be convertible by simply prepending several comment lines.
+
+
+## General guidelines
+
+* Space-separated columns.
+
+* Lines prefixed with `#` are comments.  Any line that is not a comment or blank contains data.
+
+* The type of file and column order is specified in the first line of the file via a shebang-style comment line
+beginning with `#!`.  The purpose of the `#!` is to provide a special comment that may be ignored by simple parsers but
+contains specific information that some programs require.  See following sections for details.
+
+* Multiple events may be present in a single file and are separated by one or more blank or comment lines.
+
+* Multiple files may be concatenated together.
+
+
+### Shebang line
+
+The shebang line must be the first line of the file.  It specifies the file type and order of data columns:
+
+    #!OSCAR2013 filetype columns
+
+where
+
+    filetype ::= (full-evolution nt nx ny nz | hypersurface | particles) 
+    columns ::= column1 [column2 ...]
+
+Each `columnN` is a label for the quantity in that data column.  The acceptable columns are different for each file
+type, see following sections.  Columns may be specified in arbitrary order.
+
+
+## File types
+
+### Hydro full evolution
+
+The shebang line has the following format:
+
+    #!OSCAR2013 full-evolution nt nx ny nz columns
+
+where `nt`, `nx`, `ny`, `nz` are the total numbers of grid points in each dimension.  `nz = 1` for boost-invariant
+hydro.  The minimal set of columns is
+
+    it ix iy iz : t,x,y,z indices
+    t x y z     : coordinates of fluid cell
+    vx vy vz    : fluid flow velocity
+    e p T       : energy density, pressure, temperature
+
+`t x y z` may be replaced by `tau x y eta`.
+
+For example, suppose a hydro code runs on a 51 x 51 x 51 spatial grid, steps of 0.5 fm from -12.5 to 12.5 fm, with 100
+timesteps from 0 to 10 fm.  The following would be a valid file:
+
+    #!OSCAR2013 full-evolution 100 50 50 50 it ix iy iz t x y z vx vy zx e p T
+    # this is a comment and will be ignored
+    # data begins on next line
+    0 0 0 0 0.0 -12.5 -12.5 -12.5 1.0 1.0 1.0 2.0 3.0 4.0
+    0 1 0 0 0.0 -12.0 -12.5 -12.5 1.1 0.9 1.2 2.2 3.3 4.4
+    ...
+    1 0 0 0 0.1 -12.5 -12.5 -12.5 1.1 0.9 1.2 2.2 3.3 4.4
+    ...
+    99 50 50 50 10.0 12.5 12.5 12.5 1.1 0.9 1.2 2.2 3.3 4.4
+    # the previous line was the last of the event
+    # now a new event is starting
+
+    #!OSCAR2013 full-evolution 100 50 50 50 it ix iy iz t x y z vx vy zx e p T
+    ...
+
+
+### Hydro hypersurface
+
+The shebang format is
+
+    #!OSCAR2013 hypersurface columns
+
+The minimal set of columns is
+
+    t x y z         : coordinates of fluid cell
+    vx vy vz        : fluid flow velocity
+    e p T           : energy density, pressure, temperature
+    dst dsx dsy dsz : fluid cell normal vector dsigma_mu
+
+For example
+
+    #!OSCAR2013 hypersurface t x y z vx vy vz e p T dst dsx dsy dsz
+    5.0 -6.5 3.0 7.0 -1.0 0.5 2.0 1.0 1.0 1.0 2.0 3.0 4.0 5.0
+    ...
+
+
+### Particle evolution
+
+The shebang format is
+
+    #!OSCAR2013 particles columns
+
+The minimal set of columns is
+
+    ID          : PDG particle ID
+    t x y z     : spacetime vector
+    p0 px py pz : energy-momentum vector
+
+For example
+
+    #!OSCAR2013 particles ID t x y z p0 px py pz
+    211 10.0 5.0 5.0 5.0 10.0 -3.0 -4.0 -5.0
+    ...