Grape

A Swift library for force simulation and graph visualization.

Examples

Force Directed Graph

This is a force directed graph visualizing the network of character co-occurence in Les Misérables. Take a closer look at the animation:

Source code: Miserables.swift.

Force Directed Graph in visionOS

This is the same graph as the first example, rendered in RealityView:

Source code: ForceDirectedGraph3D/ContentView.swift.

Mermaid Visualization

Dynamical graph structure based on your input, with tap and drag gesture supports, all within 100 lines of view body.

Source code: MermaidVisualization.swift

Lattice Simulation

This is a 36x36 force directed lattice like Force Directed Lattice:

Source code: Lattice.swift

Installation

To use Grape in an Xcode project by adding it to your project as a package:

https://github.com/li3zhen1/Grape

To use Grape in a SwiftPM project, add this to your Package.swift:

dependencies: [
    .package(url: "https://github.com/li3zhen1/Grape", from: "0.6.1")
]

.product(name: "Grape", package: "Grape"),

Get started

Grape ships 2 modules:

• The Grape module allows you to create force-directed graphs in SwiftUI Views.
• The ForceSimulation module is the underlying mechanism of Grape, and it helps you to create more complicated or customized force simulations. It also contains a KDTree data structure built with performance in mind, which can be useful for spatial partitioning tasks.

The Grape module

For detailed usage, please refer to documentation. A quick example here:

import Grape

struct MyGraph: View {
    @State var isRunning = true // start moving once appeared.
    
    var body: some View {
        ForceDirectedGraph($isRunning) {
            
            // Declare nodes and links like you would do in Swift Charts.
            NodeMark(id: 0).foregroundStyle(.green)
            NodeMark(id: 1).foregroundStyle(.blue)
            NodeMark(id: 2).foregroundStyle(.yellow)

            Series(0..<2) { i in
                LinkMark(from: i, to: i+1)
            }
            
        } force: {
            LinkForce()
            CenterForce()
            ManyBodyForce()
        }
    }
}

The ForceSimulation module

import simd
import ForceSimulation

// assuming you’re simulating 4 nodes
let nodeCount = 4


// Connect them
let links = [(0, 1), (1, 2), (2, 3), (3, 0)] 

/// Create a 2D force composited with 4 primitive forces.
let myForce = SealedForce2D {
    // Forces are namespaced under `Kinetics<Vector>`
    // here we only use `Kinetics<SIMD2<Double>>`, i.e. `Kinetics2D`
    Kinetics2D.ManyBodyForce(strength: -30)
    Kinetics2D.LinkForce(
        stiffness: .weightedByDegree(k: { _, _ in 1.0 }),
        originalLength: .constant(35)
    )
    Kinetics2D.CenterForce(center: .zero, strength: 1)
    Kinetics2D.CollideForce(radius: .constant(3))
}

/// Create a simulation, the dimension is inferred from the force.
let mySimulation = Simulation(
    nodeCount: nodeCount,
    links: links.map { EdgeID(source: $0.0, target: $0.1) },
    forceField: myForce
) 

/// Force is ready to start! run `tick` to iterate the simulation.

for mySimulation in 0..<120 {
    mySimulation.tick()
    let positions = mySimulation.kinetics.position.asArray()
    /// Do something with the positions.
}

Roadmap

Performance

Simulation

Grape uses simd to calculate position and velocity. Currently it takes ~0.005 seconds to iterate 120 times over the example graph(2D). (77 vertices, 254 edges, with manybody, center, collide and link forces. Release build on a M1 Max, tested with command swift test -c release)

For 3D simulation, it takes ~0.008 seconds for the same graph and same configs.

KDTree

The BufferedKDTree from this package is ~22x faster than GKQuadtree from Apple’s GameKit, according to this test case. However, please note that comparing Swift structs with NSObjects is unfair, and their behaviors are different.

Credits

This library has been greatly influenced by the outstanding work done by D3.js (Data-Driven Documents).