API Reference

This section documents the internal modules of Dymion.

Core

class dymion.core.vector.Vector(x: float, y: float, z: float = 0.0)

Bases: object

A professional 2D/3D Vector class to handle physics coordinates.

property magnitude: float

Return the Euclidean norm of the vector.

normalize() → Vector

Returns a unit vector in the same direction

dymion.core.io.export_to_json(data: List[Dict], filename: str = 'simulation.json')

Exports a list of simulation steps to a JSON file. Example data: [{‘time’: 0, ‘pos’: Vector(0,0,0)}, …]

Kinematics

class dymion.kinematics.linear.Particle(position: Vector | None = None, velocity: Vector | None = None, acceleration: Vector | None = None)

Bases: object

Represents a point mass in space with kinematic properties.

update(dt: float)

Updates the particle’s state (position and velocity) after a time interval ‘dt’. This uses Euler integration, the standart for simple physics engines.

dymion.kinematics.linear.calculate_position(initial_position: Vector, initial_velocity: Vector, time: float, acceleration: Vector = Vector(x=0.0, y=0.0, z=0.0)) → Vector

Calculates the final position using the SUVAR equation: r = r0 + v0*t + 0.5*a*t^2

dymion.kinematics.linear.calculate_velocity(initial_velocity: Vector, acceleration: Vector, time: float) → Vector

Calculates the final velocity: v = v0 + a*t

dymion.kinematics.circular.calculate_angular_position(theta0: float, omega0: float, t: float, alpha: float = 0.0) → float

Calculates final angle (radians) using theta = theta 0 + omega0*t + 0.5*alpha*t^2

dymion.kinematics.circular.calculate_angular_velocity(omega0: float, alpha: float, t: float) → float

Calculates final angular velocity (rad/s): omega = omega0 + alpha*t

dymion.kinematics.circular.get_centripetal_acceleration(omega: float, radius: float) → float

a_c = omega^2 * r

dymion.kinematics.circular.get_tangential_velocity(omega: float, radius: float) → float

v = omega * r

dymion.kinematics.circular.polar_to_cartesian(radius: float, theta: float) → Vector

Converts polar coordinates (r, theta) to a 2D Vector(x, y).

Dynamics

class dymion.dynamics.body.Body(mass: float = 1.0, material: Material = Material(name='Steel', density=7850.0, restitution=0.6, static_friction=0.74, kinetic_friction=0.57), moment_of_inertia: float = 1.0, position: Vector | None = None, velocity: Vector | None = None, acceleration: Vector | None = None)

Bases: Particle

A Body is a Particle with mass and moment of inertia, allowing for both linear (forces) and rotational (torques) dynamics.

apply_force(force: Vector)

Adds a force vector to the body.

apply_torque(torque: Vector)

Adds a torque (rotational force) to the body.

clear_forces()

Clears all linear forces acting on the body.

clear_torques()

Clears all rotational torques acting on the body.

update(dt: float)

Updates both linear and rotational state based on Newton’s Laws.

class dymion.dynamics.materials.Material(name: str, density: float, restitution: float, static_friction: float, kinetic_friction: float)

Bases: object

Represents physical properties of a material

density: float

kinetic_friction: float

name: str

restitution: float

static_friction: float

dymion.dynamics.forces.air_resistance(body: Body, rho: float, drag_coefficient: float, area: float) → Vector

Drag Equation: F_d = 1/2 * rho * v^2 * C_d * A Rho is air density, C_d is drag coefficient, A is cross-sectional area.

dymion.dynamics.forces.buoyancy_force(fluid_density: float, submerged_volume: float, g: float = 9.80665) → Vector

Archimedes’ Principle: F_b = rho * V * g Points upwards (+Y).

dymion.dynamics.forces.centrifugal_force(body: Body, omega: float, radius: float) → Vector

Calculates the centrifugal (fictitious) force experienced in a rotating frame. F_f = m * omega^2 * r The force vector points away from the center of rotation (along r).

dymion.dynamics.forces.centripetal_force(body: Body, omega: float, radius: float) → Vector

Calculates the centripetal force required to keep a body in a circular path. F_c = m * omega^2 * r

dymion.dynamics.forces.escape_velocity(mass_of_planet: float, radius: float) → float

Calculates the minimum speed needed to escape a planet’s gravity. v = sqrt(2 * G * M / r)

dymion.dynamics.forces.friction(body: Body, mu: float, normal_force: float) → Vector

Calculates the kinetic friction force: F_f = mu * N The force always opposes the direction of velocity

dymion.dynamics.forces.gravity(body: Body, g: float = 9.80665) → Vector

Calculates the weight force acting on a body: F = m * g By default, it uses Earth’s gravity pointing downwards (-Y)

dymion.dynamics.forces.spring_force(k: float, displacement: Vector) → Vector

Hooke’s Law: F = -k * x ‘k’ is the spring constant, ‘displacement’ is the vector from equilibrium.

dymion.dynamics.forces.universal_gravitation(body1: Body, body2: Body) → Vector

Calculates the gravitational force between two bodies: F = G * (m1 * m2) / r^2 The force is returned as a vector acting on body1.

dymion.dynamics.energy.elastic_potential_energy(k: float, displacement_magnitude: float) → float

Calculate the elastic potential energy stored in a spring.

Elastic potential energy is the energy stored as a result of deforming an elastic object, such as a spring. Formula: Ee = 1/2 * k * x^2

Parameters:

• k (float) – The spring constant (stiffness) in newtons per meter (N/m).

• displacement_magnitude (float) – The magnitude of displacement from the equilibrium position in meters (m).

Returns:

The elastic potential energy in joules (J).

Return type:

float

Examples

>>> elastic_potential_energy(k=100.0, displacement_magnitude=0.1)
0.5

dymion.dynamics.energy.gravitational_potential_energy(body: Body, height: float, g: float = 9.80665) → float

Calculate the gravitational potential energy of a body.

Gravitational potential energy is the energy an object possesses due to its position in a gravitational field. Formula: Ep = m * g * h

Parameters:

• body (Body) – The body object containing mass information.

• height (float) – The height of the body above the reference point in meters (m).

• g (float, optional) – The acceleration due to gravity in m/s^2. Default is G_EARTH (9.81 m/s^2).

Returns:

The gravitational potential energy of the body in joules (J).

Return type:

float

Examples

>>> body = Body(mass=5.0, velocity=Vector(0.0, 0.0, 0.0))
>>> gravitational_potential_energy(body, height=10.0)
490.5

dymion.dynamics.energy.kinetic_energy(body: Body) → float

Calculate the kinetic energy of a body.

Kinetic energy is the energy possessed by an object due to its motion. Formula: Ek = 1/2 * m * v^2

Parameters:

body (Body) – The body object containing mass and velocity information.

Returns:

The kinetic energy of the body in joules (J).

Return type:

float

Examples

>>> body = Body(mass=10.0, velocity=Vector(2.0, 0.0, 0.0))
>>> kinetic_energy(body)
20.0

dymion.dynamics.energy.mechanical_energy(body: Body, height: float, g: float = 9.80665) → float

Calculate the total mechanical energy of a body.

Mechanical energy is the sum of kinetic energy and potential energy in a system. Formula: E_mech = Ek + Ep

Parameters:

• body (Body) – The body object containing mass and velocity information.

• height (float) – The height of the body above the reference point in meters (m).

• g (float, optional) – The acceleration due to gravity in m/s^2. Default is G_EARTH (9.81 m/s^2).

Returns:

The total mechanical energy of the body in joules (J).

Return type:

float

Examples

>>> body = Body(mass=10.0, velocity=Vector(3.0, 0.0, 0.0))
>>> mechanical_energy(body, height=5.0)
740.5

dymion.dynamics.energy.power(work_done: float, time: float) → float

Calculate the power when work is done over a time interval.

Power is the rate at which work is done or energy is transferred. Formula: P = W / t

Parameters:

• work_done (float) – The work done in joules (J).

• time (float) – The time interval in seconds (s). Must be positive.

Returns:

The power in watts (W). Returns 0.0 if time is zero or negative.

Return type:

float

Examples

>>> power(work_done=100.0, time=10.0)
10.0

dymion.dynamics.energy.work(force: Vector, displacement: Vector) → float

Calculate the work done by a force on an object.

Work is the dot product of force and displacement vectors. Formula: W = F · d = |F| * |d| * cos(θ)

Parameters:

• force (Vector) – The force vector acting on the object in newtons (N).

• displacement (Vector) – The displacement vector in meters (m).

Returns:

The work done in joules (J).

Return type:

float

Examples

>>> F = Vector(10.0, 0.0, 0.0)
>>> d = Vector(5.0, 0.0, 0.0)
>>> work(F, d)
50.0

dymion.dynamics.momentum.elastic_collision_1d(m1: float, v1: float, m2: float, v2: float) → tuple[float, float]

Calculates final velocities for a perfect 1D elastic collision. Returns (v1_final, v2_final)

dymion.dynamics.momentum.impulse(force: Vector, time_interval: float) → Vector

Calculates the Impulse (J): J = F * Δt Impulse is also equal to the change in momentum.

dymion.dynamics.momentum.inelastic_collision_1d(m1: float, v1: float, m2: float, v2: float) → float

Calculates the final velocity for a perfectly inelastic collision (objects stick together). v_final = (m1*v1 + m2*v2) / (m1 + m2)

dymion.dynamics.momentum.linear_momentum(body: Body) → Vector

Calculates the linear momentum (p): p = m * v

dymion.dynamics.momentum.resolve_collision_2d(body1: Body, body2: Body)

Resolves a 2D elastic collision between two bodies. Updates their velocities based on conservation of momentum and energy.

dymion.dynamics.rotational.calculate_torque(lever_arm: Vector, force: Vector) → Vector

Calculates Torque (tau) = r x F. r is the vector from the axis of rotation to the point where force is applied.

dymion.dynamics.rotational.inertia_cylinder(mass: float, radius: float) → float

I = 1/2 * m * r^2

dymion.dynamics.rotational.inertia_rod_center(mass: float, length: float) → float

I = 1/12 * m * L^2

dymion.dynamics.rotational.inertia_sphere(mass: float, radius: float) → float

I = 2/5 * m * r^2

dymion.dynamics.systems.calculate_center_of_mass(bodies: List[Body]) → Vector

Calculates the center of mass for a system of multiple bodies. R = (sum(m_i * r_i)) / sum(m_i)

dymion.dynamics.systems.calculate_total_momentum(bodies: List[Body]) → Vector

Calculates the total linear momentum of a system of bodies. P = sum(m_i * v_i)

dymion.dynamics.collisions.intersect_aabb(min1: Vector, max1: Vector, min2: Vector, max2: Vector) → bool

Checks if two Axis-Aligned Bounding Boxes (AABB) intersect.

dymion.dynamics.collisions.intersect_circles(pos1: Vector, radius1: float, pos2: Vector, radius2: float) → bool

Checks if two circles/spheres intersect.

dymion.dynamics.statics.is_static_equilibrium(body: Body, tolerance: float = 1e-06) → bool

Checks if a body is in static equilibrium (Net Force ≈ 0 and Net Torque ≈ 0).