added description and images

.gitignore

@@ -0,0 +1 @@
+.DS_Store

README.md

@@ -0,0 +1,60 @@
+
+<p align="center"><img src="https://raw.githubusercontent.com/nilsleiffischer/cbc-playground/master/banner.png"></p>
+
+# Gravitational waves playground
+
+In this [Swift playground book](http://www.apple.com/swift/playgrounds/) you can make [gravitational waves](https://en.wikipedia.org/wiki/Gravitational_wave) visible and control the visualization of this elusive radiation emitted by two inspiraling and merging black holes. It continues my series of interactive iPad simulations that started with my [playground book on black holes](https://nilsleiffischer.de/black-holes-playground/).
+
+- Adjust the black hole masses:
+
+  ![Images/masses.gif](Images/masses.gif)
+
+- Control visualization parameters, such as wave polarization and colors:
+
+  ![Images/polarization.gif](Images/polarization.gif)
+
+- Explore the visualization in three dimensions:
+
+  ![Images/perspective.gif](Images/perspective.gif)
+
+
+## Installation
+
+1. [Download the Swift Playgrounds App](https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=908519492&mt=8&ls=1) on your iPad.
+2. [Download the Gravitational Waves playground file](https://github.com/knly/cbc-playground/raw/master/dist/Gravitational%waves.playgroundbook.zip) on your iPad or Mac:
+
+  - **On your iPad:** Select _Open with "Playgrounds"_.
+
+    ![iPad download](Images/ipad_download.png)
+
+  - Or **on your Mac:** [AirDrop](https://support.apple.com/en-us/HT203106) the file to your iPad and select _Open with "Playgrounds"_.
+
+    ![AirDrop](Images/airdrop.png)
+
+
+## Gallery
+
+![Images/gallery_rgb.gif](Images/gallery_rgb.gif)
+
+![Images/gallery_red.gif](Images/gallery_red.gif)
+
+![Images/gallery_merger.gif](Images/gallery_merger.gif)
+
+
+## Simulated physics
+
+- The rendered field is the lowest-order metric perturbation in TT-gauge (or _gravitational wave strain_) $h_\plus$ or $h_\cross$, with their $\frac{1}{r}$ distance scaling removed.
+- Selecting the option `showFrequencyScaling` is equivalent to visualising the real or imaginary part of the Weyl scalar $\Psi_4$, depending on the chosen polarization.
+- The six colors are chosen from the normalized field values discretized into bins with edges $\left{\pm 1, \pm 0.7, \pm 0.5, \pm 0.3\right}$.
+- The rotating spheres depict the relative Schwarzschild radius of the black holes, with an arbitary rescaling for visualisation.
+- Orbital separation, time and wave propagation speed are also arbitrarily rescaled. Relative quantities are correct, however.
+- The ringdown is modeled as a simple quadrupolar oscillation with an exponential decay in amplitude for visualisation purposes only.
+
+
+## About this project
+
+I created this Swift playground book as part of my application for the Apple WWDC 2018 scholarship. It allows the reader to discover physics that is invisible to our eyes by simulating it on screen and by controlling its visual representation. The volume rendering of the gravitational field is accomplished by a library of [Metal](https://developer.apple.com/metal/) shaders that apply to a [SceneKit](https://developer.apple.com/scenekit/) scene. The shaders perform ray-tracing through three-dimensional space and integrate the gravitational field along each ray. By translating the field values to colors and blending them together along the ray, I create a visual representation of the gravitational field in space.
+
+- Author: [Nils Leif Fischer](https://nilsleiffischer.de)
+
+Copyright (c) 2018 Nils Leif Fischer

TestingShaders/BinarySystemViewController.swift

@@ -61,16 +61,16 @@ public struct VisualConfiguration {
     /// Color chosen for small positive field values
     public var tertiaryPositiveColor: UIColor? = nil
     /// Colors chosen for large negative field values
-    public var primaryNegativeColor: UIColor? = .yellow
+    public var primaryNegativeColor: UIColor? = .green
     /// Color chosen for intermediate negative field values
     public var secondaryNegativeColor: UIColor? = nil
     /// Color chosen for small negative field values
     public var tertiaryNegativeColor: UIColor? = nil
 
     /// Size of smallest substructure that the volume rendering can resolve. Lowering this value can heavily decrease rendering framerate.
-    public var resolution: Float = 0.4
+    public var resolution: Float = 0.3
     /// The increase in opacity when looking through one unit of distance. Lower values make the volume rendering appear more transparent.
-    public var opticalDensity: Float = 0.25
+    public var opticalDensity: Float = 0.3
 
     /// Enable to visualize the physical quantity Psi4 that scales with the frequency squared, instead of the gravitational wave strain
     public var showFrequencyScaling: Bool = false
@@ -80,6 +80,8 @@ public struct VisualConfiguration {
 
 public class BinarySystemViewController: UIViewController, SCNSceneRendererDelegate, ARSCNViewDelegate, ARSessionDelegate {
 
+    private var binarySystem = BinarySystem()
+    private var timeToMerger: TimeInterval = 15
 
     // MARK: Scales
 
@@ -201,9 +203,9 @@ public class BinarySystemViewController: UIViewController, SCNSceneRendererDeleg
         #pragma body
 
         float t = (scn_frame.time - mergerTime) * timeScale;
-        float f = pow(chirpMass, -5.0 / 8.0) * pow(abs(t), -3.0 / 8.0);
+        float f = pow(chirpMass, -5.0 / 8.0) * pow(abs(t), -3.0 / 8.0);//pow(chirpMass, -5.0 / 8.0) * pow(15.0 * 200.0, -3.0 / 8.0);
 
-        float orbitalAngle = step(0.0, -t) * M_PI_F * pow(f * chirpMass, -5.0 / 3.0) + initialOrbitalAngle;
+        float orbitalAngle = step(0.0, -t) * M_PI_F * pow(f * chirpMass, -5.0 / 3.0)/*f * -t*/ + initialOrbitalAngle;
         float orbitalSeparation = orbitalSeparationScale * pow(chirpMass / 4.0, 1.0 / 3.0) * pow(M_PI_F * f, -2.0 / 3.0);
         float3 x = float3(orbitalSeparationFraction * orbitalSeparation, M_PI_2_F, orbitalAngle);
         float3 objectCenter = x.x * float3(cos(x.z) * sin(x.y), cos(x.y), -sin(x.z) * sin(x.y));
@@ -236,14 +238,12 @@ public class BinarySystemViewController: UIViewController, SCNSceneRendererDeleg
         float vertexDistance = objectSizeScale * schwarzschildRadius * (1.0 + ringdownAmplitude * (pow(sin(theta) * sin(2 * M_PI_F * ringdownFrequency * t / timeScale + phi), 2.0) - 0.5));
         
         _geometry.position = float4(vertexDistance * objectRadialUnit, 1.0);
+        // TODO: also update normal
         """
 
 
     // MARK: Public interface
 
-    private var binarySystem = BinarySystem()
-    private var timeToMerger: TimeInterval = 15
-
     /// Simulates a binary system that merges in `timeToMerger` (real-time) seconds from now.
     public func simulate(_ binarySystem: BinarySystem, mergingIn timeToMerger: TimeInterval) {
         self.binarySystem = binarySystem
@@ -369,6 +369,7 @@ public class BinarySystemViewController: UIViewController, SCNSceneRendererDeleg
         let margins = view.layoutMarginsGuide
         restartButton.trailingAnchor.constraint(equalTo: margins.trailingAnchor).isActive = true
         restartButton.centerYAnchor.constraint(equalTo: margins.centerYAnchor).isActive = true
+        restartButton.isHidden = true
 
         // Apply default visual configuration
         if self.visualConfiguration == nil {

TestingShaders/volume_rendering.metal

@@ -30,12 +30,13 @@ float3 polarToCartesian(float3 x) {
 /// Gravitational wave emission and orbital rotation frequency
 float frequency(float t_ret, float chirpMass) {
     return pow(chirpMass, -5.0 / 8.0) * pow(abs(t_ret), -3.0 / 8.0);
+//    return pow(chirpMass, -5.0 / 8.0) * pow(15.0 * 200.0, -3.0 / 8.0);
 }
 
 /// Position of the black holes in inspiraling orbit around each other
 float3 objectPosition(float t, float chirpMass, float initialOrbitalAngle, float orbitalSeparationScale, float orbitalSeparationFraction) {
     float f = frequency(t, chirpMass);
-    float orbitalAngle = M_PI_F * pow(f * chirpMass, -5.0 / 3.0) + initialOrbitalAngle;
+    float orbitalAngle = M_PI_F * pow(f * chirpMass, -5.0 / 3.0)/*f * -t*/ + initialOrbitalAngle;
     float orbitalSeparation = orbitalSeparationScale * pow(chirpMass / 4.0, 1.0 / 3.0) * pow(M_PI_F * f, -2.0 / 3.0);
     return polarToCartesian(float3(orbitalSeparationFraction * orbitalSeparation, M_PI_2_F, orbitalAngle));
 }
@@ -233,10 +234,8 @@ fragment half4 renderVolume(VolumeRenderingVertexIO in [[stage_in]],
 
         // Decide for a color based on field value
         float4 color;
-//        if (fieldValue <= parameters.upperThreshold && fieldValue > parameters.middleThreshold) {
         if (fieldValue > 0.7) {
             color = parameters.primaryPositiveColor;
-//        } else if (fieldValue > parameters.lowerThreshold) {
         } else if (fieldValue > 0.5) {
             color = parameters.secondaryPositiveColor;
         } else if (fieldValue > 0.3) {