Merge pull request #1 from source-academy/dev

Init source code and build config

.eslintrc.test.cjs

@@ -0,0 +1,12 @@
+module.exports = {
+  env: {
+    jest: true,
+  },
+  extends: ["./.eslintrc.base.cjs", "plugin:jest/recommended"],
+  plugins: ["jest"],
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: "./tsconfig.test.json",
+  },
+};

.gitignore

@@ -0,0 +1 @@
+node_modules

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "eslint.workingDirectories": ["src"],
+  "[typescript]": {
+    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
+  },
+  "eslint.format.enable": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "always",
+    "source.fixAll": "always"
+  },
+  "files.eol": "\r\n"
+}

README.md

@@ -1,2 +1,17 @@
 # nbody
-N-body simulations as a Source Academy module 
+
+N-body simulations as a Source Academy module
+
+## Installation
+
+TODO
+
+## Usage
+
+TODO
+
+## For developers
+
+TODO
+
+npm install [email protected] @types/three@0.158.0

dist/index.js.LICENSE.txt

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2010-2023 Three.js Authors
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * lil-gui
+ * https://lil-gui.georgealways.com
+ * @version 0.19.2
+ * @author George Michael Brower
+ * @license MIT
+ */

dist/src/CelestialBody.d.ts

@@ -0,0 +1,28 @@
+import { type Vector3 } from 'three';
+/**
+ * Represents a celestial body with all of its kinematic properties.
+ */
+export declare class CelestialBody {
+    readonly label: string;
+    readonly mass: number;
+    position: Vector3;
+    velocity: Vector3;
+    acceleration: Vector3;
+    /**
+     * Create a new CelestialBody with the provided information.
+     * @param label label of the body.
+     * @param mass mass of the body.
+     * @param position position of the body.
+     * @param velocity velocity of the body.
+     * @param acceleration acceleration of the body.
+     */
+    constructor(label: string, mass: number, position: Vector3, velocity: Vector3, acceleration: Vector3);
+    /**
+     * Deep copy the current CelestialBody with the updated kinematic properties.
+     * @param position new position.
+     * @param velocity new velocity.
+     * @param acceleration new acceleration.
+     * @returns a new CelestialBody instance with the updated properties.
+     */
+    clone(position?: Vector3, velocity?: Vector3, acceleration?: Vector3): CelestialBody;
+}

dist/src/Force.d.ts

@@ -0,0 +1,25 @@
+import type { Vector3 } from 'three';
+import type { CelestialBody } from './CelestialBody';
+/**
+ * Represents a force object used to calculate forces acting on the bodies in the Universe.
+ */
+export interface Force {
+    getForces(bodies: CelestialBody[]): Vector3[];
+}
+/**
+ * Function object that uses the user-defined lambda function to calculate the forces acting on the bodies.
+ */
+export declare class LambdaForce implements Force {
+    readonly fn: (bodies: CelestialBody[]) => Vector3[];
+    /**
+     * Create a new LambdaForce with the provided lambda function. Lambda function should take in an array of CelestialBodies and return an array of forces acting on the bodies.
+     * @param fn lambda function.
+     */
+    constructor(fn: (bodies: CelestialBody[]) => Vector3[]);
+    /**
+     * Get the forces acting on the bodies.
+     * @param bodies array of CelestialBodies.
+     * @returns array of forces acting on the bodies.
+     */
+    getForces(bodies: CelestialBody[]): Vector3[];
+}

dist/src/SimulateFunction.d.ts

@@ -0,0 +1,33 @@
+import type { State } from './State';
+/**
+ * Represents a function object used for simulating the Universe. Should encapsulate the numerical integration method and other necessary simulation logic. Can use an external force calculation function object - see {@link Force}.
+ */
+export interface SimulateFunction {
+    /**
+     * Simulate a step in the Universe by using the previous and/or current state and a time step.
+     * @param deltaT time step.
+     * @param currState current state of the Universe.
+     * @param prevState previous state of the Universe.
+     * @returns the next state of the Universe.
+     */
+    simulate(deltaT: number, currState: State, prevState: State): State;
+}
+/**
+ * Function object that uses the user-defined lambda function to simulate the Universe.
+ */
+export declare class LambdaSim implements SimulateFunction {
+    readonly fn: (deltaT: number, currState: State, prevState: State) => State;
+    /**
+     * Create a new LambdaSim with the provided lambda function. The lambda function should call or calculate the forces action on the bodies by itself.
+     * @param fn lambda function.
+     */
+    constructor(fn: (deltaT: number, currState: State, prevState: State) => State);
+    /**
+     * Simulate the Universe using the lambda function.
+     * @param deltaT time step.
+     * @param currState current state of the Universe.
+     * @param prevState previous state of the Universe.
+     * @returns the next state of the Universe.
+     */
+    simulate(deltaT: number, currState: State, prevState: State): State;
+}

dist/src/Simulation.d.ts

@@ -0,0 +1,121 @@
+import { type Universe } from './Universe';
+import { type Visualizer } from './Visualizer';
+export type VisType = '2D' | '3D';
+export type ControllerType = 'default' | 'manual' | 'none';
+/**
+ * A Simulation object that contains Universes and a Visualizer.
+ */
+export declare class Simulation {
+    readonly visualizer: Visualizer;
+    /**
+     * Array of Universes that make up this simulation. All universes are simulated independently and visualized together.
+     */
+    readonly universes: Universe[];
+    readonly controller: ControllerType;
+    maxFrameRate: number;
+    maxTrailLength: number;
+    looped: boolean;
+    controls: {
+        speed: number;
+        paused: boolean;
+        showTrails: boolean;
+        showUniverse: {
+            [key: string]: boolean;
+        };
+    };
+    showDebugInfo: boolean;
+    /**
+     * Create a new Simulation object with the provided Universes and visualization config.
+     * @param universes array of Universes.
+     * @param visType visualization type.
+     * @param record whether to record the simulation.
+     * @param looped whether to loop the recorded simulation.
+     * @param controller controller type.
+     * @param showTrails whether to show trails in the visualization.
+     * @param showDebugInfo whether to show debug info in the visualization.
+     * @param maxFrameRate maximum frame rate of the visualization.
+     * @param maxTrailLength maximum trail for each universe.
+     */
+    constructor(universes: Universe | Universe[], { visType, record, looped, controller, showTrails, showDebugInfo, maxFrameRate, maxTrailLength, }: {
+        visType?: VisType;
+        record?: boolean;
+        looped?: boolean;
+        controller?: ControllerType;
+        showTrails?: boolean;
+        showDebugInfo?: boolean;
+        maxFrameRate?: number;
+        maxTrailLength?: number;
+    });
+    /**
+     * Get the speed of the simulation.
+     * @returns speed of the simulation as a scale of normal time.
+     */
+    getSpeed(): number;
+    /**
+     * Set the speed of the simulation. Only works if the controller is 'manual'.
+     * @param speed speed of the simulation as a scale of normal time.
+     */
+    setSpeed(speed: number): void;
+    /**
+     * Get whether the simulation is playing.
+     * @returns true if the simulation is playing.
+     */
+    isPlaying(): boolean;
+    /**
+     * Pause the simulation. Only works if the controller is 'manual'.
+     */
+    pause(): void;
+    /**
+     * Resume the simulation. Only works if the controller is 'manual'.
+     */
+    resume(): void;
+    /**
+     * Get whether trails are shown in the visualization.
+     * @returns true if trails are shown.
+     */
+    getShowTrails(): boolean;
+    /**
+     * Set whether to show trails in the visualization. Only works if the controller is 'manual'.
+     * @param showTrails true to show trails.
+     */
+    setShowTrails(showTrails: boolean): void;
+    /**
+     * True if the universe with the given label is shown.
+     * @param label universe label.
+     * @returns whether the universe is shown.
+     */
+    getShowUniverse(label: string): boolean;
+    /**
+     * Set whether to show the universe with the given label. Only works if the controller is 'manual'.
+     * @param label universe label.
+     * @param show true to show the universe.
+     */
+    setShowUniverse(label: string, show: boolean): void;
+    /**
+     * Get the maximum trail length used in the visualization.
+     * @returns maximum trail length.
+     */
+    getMaxTrailLength(): number;
+    /**
+     * Set the maximum trail length used in the visualization. Changes only apply on the next Simulation.play() call.
+     * @param maxTrailLength maximum trail length.
+     */
+    setMaxTrailLength(maxTrailLength: number): void;
+    /**
+     * Simulates a single step in this simulation.
+     * @param deltaT time step to simulate.
+     */
+    simulateStep(deltaT: number): void;
+    /**
+     * Insert the simulation visualization in the div with the given id.
+     * @param divId div id.
+     * @param speed initial time scale.
+     * @param paused whether to start the simulation paused.
+     * @param recordFor number of seconds to record for, only used if in record mode.
+     */
+    start(divId: string, width: number, height: number, speed?: number, paused?: boolean, recordFor?: number): void;
+    /**
+     * Stop the simulation.
+     */
+    stop(): void;
+}

dist/src/State.d.ts

@@ -0,0 +1,20 @@
+import type { CelestialBody } from './CelestialBody';
+/**
+ * Represents a Universe's state snapshot.
+ */
+export declare class State {
+    /**
+     * Array of celestial bodies that make up this state of the Universe.
+     */
+    readonly bodies: CelestialBody[];
+    /**
+     * Create a new State with the given celestial bodies.
+     * @param bodies array of celestial bodies.
+     */
+    constructor(bodies: CelestialBody[]);
+    /**
+     * Deep copy this state
+     * @returns a new State instance.
+     */
+    clone(): State;
+}

dist/src/Transformation.d.ts

@@ -0,0 +1,31 @@
+import { type State } from './State';
+/**
+ * Represents a Frame of Reference transformation.
+ */
+export interface Transformation {
+    /**
+     * Transform the state to a new frame of reference.
+     * @param state state to transform.
+     * @param deltaT time step taken to get to this state. Only applicable for time-dependent transformations.
+     * @returns transformed state.
+     */
+    transform(state: State, deltaT: number): State;
+}
+/**
+ * A Frame of Reference transformation that uses the user-defined lambda function.
+ */
+export declare class LambdaTransformation implements Transformation {
+    readonly fn: (state: State, deltaT: number) => State;
+    /**
+     * Create a new LambdaTransformer with the provided lambda function.
+     * @param fn lambda function.
+     */
+    constructor(fn: (state: State, deltaT: number) => State);
+    /**
+     * Transform the state's frame of reference using the lambda function.
+     * @param state state to transform.
+     * @param deltaT time step taken to get to this state. Only applicable for time-dependent transformations.
+     * @returns transformed state.
+     */
+    transform(state: State, deltaT: number): State;
+}

dist/src/Universe.d.ts

@@ -0,0 +1,46 @@
+import { type SimulateFunction } from './SimulateFunction';
+import { type State } from './State';
+import { type Transformation } from './Transformation';
+/**
+ * Container for a Universe's configuration.
+ */
+export type UniverseConfig = {
+    prevState: State;
+    currState: State;
+    color: string | string[];
+    label: string;
+    simFunc: SimulateFunction;
+    transformations: Transformation[];
+};
+/**
+ * A Universe object that contains previous and current state of the universe, a simulation function, frame of reference transformations and other necessary data.
+ */
+export declare class Universe {
+    prevState: State;
+    currState: State;
+    /**
+     * Color of the bodies in the Universe. A single color applied to all bodies or an array of colors applied to each body respectively.
+     */
+    color: string | string[];
+    label: string;
+    simFunc: SimulateFunction;
+    /**
+     * Array of transformations to be applied to the Universe's state after simulation and before visualization.
+     */
+    transformations: Transformation[];
+    /**
+     * Create a new Universe with the provided configuration.
+     * @param config configuration object.
+     */
+    constructor(config: Partial<UniverseConfig>);
+    /**
+     * Simulate a step in the Universe using the SimulateFunction and Transformations.
+     * @param deltaT time step to simulate.
+     */
+    simulateStep(deltaT: number): void;
+    /**
+     * Deep copy the current Universe.
+     * @returns a new Universe instance.
+     */
+    clone(): Universe;
+}

dist/src/Visualizer.d.ts

@@ -0,0 +1,4 @@
+export interface Visualizer {
+    start(divId: string, width: number, height: number, recordFor: number): void;
+    stop(): void;
+}

dist/src/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * NBody is a JS/TS library for simulating and visualizing n-body systems. It provides interfaces and implementations of forces, frame of reference transformations, simulation control, and multiple modes and paradigms of visualization.
+ * @author Yeluri Ketan
+ */
+import { CelestialBody } from './CelestialBody';
+import { type Force } from './Force';
+import { CentripetalForce, CombinedForce, Gravity } from './library/Force';
+import { ExplicitEulerSim, RungeKutta4Sim, SemiImplicitEulerSim, VelocityVerletSim } from './library/SimulateFunction';
+import { LambdaSim, type SimulateFunction } from './SimulateFunction';
+import { Simulation, type VisType } from './Simulation';
+import { State } from './State';
+import { BodyCenterTransformation, CoMTransformation, RotateTransformation } from './library/Transformation';
+import { LambdaTransformation, type Transformation } from './Transformation';
+import { Universe, type UniverseConfig } from './Universe';
+import { RealTimeVisualizer, RealTimeVisualizer3D, RecordingVisualizer, RecordingVisualizer3D } from './library/Visualizer';
+import { Vector3 } from 'three';
+export { BodyCenterTransformation, CelestialBody, CentripetalForce, CombinedForce, CoMTransformation, ExplicitEulerSim, Gravity, LambdaSim, LambdaTransformation, RealTimeVisualizer, RealTimeVisualizer3D, RecordingVisualizer, RecordingVisualizer3D, RotateTransformation, RungeKutta4Sim, SemiImplicitEulerSim, Simulation, State, Universe, Vector3, VelocityVerletSim, type Force, type SimulateFunction, type Transformation, type UniverseConfig, type VisType, };