Physical particle with mass, position, velocity, and force accumulation. More...

#include <Particle.hpp>

Inheritance diagram for Phyth::Mechanics::Particle:

[legend]

Collaboration diagram for Phyth::Mechanics::Particle:

[legend]

Public Member Functions
	Particle (const Quantity< Kilogram > &mass, const Vector3< Quantity< Meter > > &position) noexcept
	Construct a particle with mass and initial position.

virtual	~Particle ()=default

void	ApplyForce (const Vector3< Quantity< Newton > > &force)
	Accumulate an external force on the particle.

virtual void	Integrate () noexcept
	Integrate equations of motion using velocity Verlet.

constexpr const auto &	GetPosition () const noexcept

void	SetPosition (const Vector3< Quantity< Meter > > &position) noexcept
	Set the particle position (m)

constexpr auto	GetMass () const noexcept

void	SetMass (const Quantity< Kilogram > &mass) noexcept
	Set the particle mass (kg)

constexpr const auto &	GetVelocity () const noexcept

void	SetVelocity (const Vector3< Quantity< MeterPerSecond > > &velocity) noexcept
	Set the particle velocity (m/s)

constexpr bool	IsFixed () const noexcept

void	SetFixed (const bool fixed) noexcept
	Set whether the particle is fixed (immovable)

constexpr const auto &	GetExternalForce () const noexcept

void	SetExternalForce (const Vector3< Quantity< Newton > > &external_force) noexcept
	Manually set the external force (N)

void	SetComputeForcesFunction (const std::function< void(Particle *)> &func) noexcept
	Set the user-defined force computation function.

Quantity< Joule >	GetPotentialEnergy (const Quantity< Meter > y_ref=0) const
	Compute gravitational potential energy relative to a reference height.

Quantity< Joule >	GetKineticEnergy () const noexcept
	Compute kinetic energy.

Quantity< Joule >	GetTotalEnergy (const Quantity< Meter > y_ref=0) const noexcept
	Compute total mechanical energy.

Protected Attributes
Quantity< Kilogram >	mass_

Vector3< Quantity< MeterPerSecond > >	velocity_ {}

bool	fixed_ {false}

Vector3< Quantity< Newton > >	external_force_ {}

Vector3< Quantity< Meter > >	position_

std::function< void(Particle *)>	compute_forces_func_

Friends
std::ostream &	operator<< (std::ostream &os, const Particle &p)
	Stream insertion operator for Particle.

Detailed Description

Physical particle with mass, position, velocity, and force accumulation.

Particle is the fundamental building block for mechanical simulations. It stores the state (position, velocity, mass) and accumulates forces applied by constraints, springs, or user-defined force functions.

Integration is performed using the velocity Verlet algorithm, which is symplectic and energy-conserving for Hamiltonian systems.

Particles can be marked as fixed (immovable), which is useful for representing anchors or boundary conditions.

Example: auto p = std::make_shared<Particle>(1_kg, Vector3{0_m, 0_m, 0_m}); p->SetComputeForcesFunction([](Particle* p) { // Apply gravity p->ApplyForce({0_N, -1_kg * Consts::g, 0_N}); });

// In simulation loop: p->Integrate(); auto total_energy = p->GetTotalEnergy();

Definition at line 36 of file Particle.hpp.

Constructor & Destructor Documentation

◆ Particle()

Phyth::Mechanics::Particle::Particle	(	const Quantity< Kilogram > &	mass,
		const Vector3< Quantity< Meter > > &	position
	)

inlinenoexcept

Construct a particle with mass and initial position.

Parameters

mass	Mass of the particle (kg)
position	Initial position (m)

Initial velocity is zero and the particle is not fixed.

Definition at line 46 of file Particle.hpp.

◆ ~Particle()

virtual Phyth::Mechanics::Particle::~Particle ( )

virtualdefault

Member Function Documentation

◆ ApplyForce()

void Phyth::Mechanics::Particle::ApplyForce ( const Vector3< Quantity< Newton > > & force )

inline

Accumulate an external force on the particle.

Forces are accumulated during the force computation phase and cleared after each integration step. This allows multiple force sources (gravity, springs, collisions) to contribute.

Parameters

force Force to apply (N)

Note: If the particle is fixed, this function does nothing.

Definition at line 63 of file Particle.hpp.

◆ GetExternalForce()

constexpr const auto & Phyth::Mechanics::Particle::GetExternalForce ( ) const

inlineconstexprnoexcept

Returns: Accumulated external force (N)

Definition at line 127 of file Particle.hpp.

◆ GetKineticEnergy()

Quantity< Joule > Phyth::Mechanics::Particle::GetKineticEnergy ( ) const

inlinenoexcept

Compute kinetic energy.

Returns: 0.5 * m * |v|^2 (J)

Definition at line 169 of file Particle.hpp.

◆ GetMass()

constexpr auto Phyth::Mechanics::Particle::GetMass ( ) const

inlineconstexprnoexcept

Returns: Mass (kg)

Definition at line 109 of file Particle.hpp.

◆ GetPosition()

constexpr const auto & Phyth::Mechanics::Particle::GetPosition ( ) const

inlineconstexprnoexcept

Returns: Current position (m)

Definition at line 103 of file Particle.hpp.

◆ GetPotentialEnergy()

Quantity< Joule > Phyth::Mechanics::Particle::GetPotentialEnergy ( const Quantity< Meter > y_ref = 0 ) const

inline

Compute gravitational potential energy relative to a reference height.

Parameters

y_ref Reference height (m), default 0

Returns: m * g * (position.y - y_ref) (J)

The default reference height is y=0. Positive energy means the particle is above the reference.

Definition at line 160 of file Particle.hpp.

◆ GetTotalEnergy()

Quantity< Joule > Phyth::Mechanics::Particle::GetTotalEnergy ( const Quantity< Meter > y_ref = 0 ) const

inlinenoexcept

Compute total mechanical energy.

Parameters

y_ref Reference height for potential energy, default 0

Returns: PotentialEnergy + KineticEnergy (J)

For conservative systems, this quantity should remain constant. Energy drift can be used as a measure of numerical accuracy.

Definition at line 182 of file Particle.hpp.

◆ GetVelocity()

constexpr const auto & Phyth::Mechanics::Particle::GetVelocity ( ) const

inlineconstexprnoexcept

Returns: Current velocity (m/s)

Definition at line 115 of file Particle.hpp.

◆ Integrate()

virtual void Phyth::Mechanics::Particle::Integrate ( )

inlinevirtualnoexcept

Integrate equations of motion using velocity Verlet.

The velocity Verlet algorithm consists of three steps:

Update position: x(t+dt) = x(t) + v(t)*dt + 0.5*a(t)*dt^2
Compute new acceleration: a(t+dt) = F(t+dt) / m
Update velocity: v(t+dt) = v(t) + 0.5*(a(t) + a(t+dt))*dt

The user-defined force function is called twice per integration step:

Once before position update (using old forces)
Once after position update (using new position)

External forces are automatically cleared at the start and end. If the particle is fixed, this function does nothing.

Reimplemented in Phyth::Electromagnetics::MagneticDipole, and Phyth::Electromagnetics::PointCharge.

Definition at line 83 of file Particle.hpp.

◆ IsFixed()

constexpr bool Phyth::Mechanics::Particle::IsFixed ( ) const

inlineconstexprnoexcept

Returns: Whether the particle is fixed (immovable)

Definition at line 121 of file Particle.hpp.

◆ SetComputeForcesFunction()

void Phyth::Mechanics::Particle::SetComputeForcesFunction ( const std::function< void(Particle *)> & func )

inlinenoexcept

Set the user-defined force computation function.

Parameters

func	Function that applies forces to the particle via ApplyForce() (Only Apply Force)

The function is called automatically during Integrate(). The default function does nothing.

Example: p->SetComputeForcesFunction([](Particle* p) { p->ApplyForce({0_N, -1_kg * Consts::g, 0_N}); // gravity });

Definition at line 147 of file Particle.hpp.

◆ SetExternalForce()

void Phyth::Mechanics::Particle::SetExternalForce ( const Vector3< Quantity< Newton > > & external_force )

inlinenoexcept

Manually set the external force (N)

Definition at line 130 of file Particle.hpp.

◆ SetFixed()

void Phyth::Mechanics::Particle::SetFixed ( const bool fixed )

inlinenoexcept

Set whether the particle is fixed (immovable)

Definition at line 124 of file Particle.hpp.

◆ SetMass()

void Phyth::Mechanics::Particle::SetMass ( const Quantity< Kilogram > & mass )

inlinenoexcept

Set the particle mass (kg)

Definition at line 112 of file Particle.hpp.

◆ SetPosition()

void Phyth::Mechanics::Particle::SetPosition ( const Vector3< Quantity< Meter > > & position )

inlinenoexcept

Set the particle position (m)

Definition at line 106 of file Particle.hpp.

◆ SetVelocity()

void Phyth::Mechanics::Particle::SetVelocity ( const Vector3< Quantity< MeterPerSecond > > & velocity )

inlinenoexcept

Set the particle velocity (m/s)

Definition at line 118 of file Particle.hpp.

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const Particle &	p
	)

friend

Stream insertion operator for Particle.

Output format: "Particle{pos=(x, y, z), mass=value}"

Definition at line 191 of file Particle.hpp.

Member Data Documentation

◆ compute_forces_func_

std::function<void(Particle *)> Phyth::Mechanics::Particle::compute_forces_func_

protected

Initial value:

= [](Particle *) {

}

Phyth::Mechanics::Particle::Particle

Particle(const Quantity< Kilogram > &mass, const Vector3< Quantity< Meter > > &position) noexcept

Construct a particle with mass and initial position.

Definition Particle.hpp:46

Definition at line 204 of file Particle.hpp.

◆ external_force_

Vector3<Quantity<Newton> > Phyth::Mechanics::Particle::external_force_ {}

protected

Definition at line 201 of file Particle.hpp.

◆ fixed_

bool Phyth::Mechanics::Particle::fixed_ {false}

protected

Definition at line 199 of file Particle.hpp.

◆ mass_

Quantity<Kilogram> Phyth::Mechanics::Particle::mass_

protected

Definition at line 197 of file Particle.hpp.

◆ position_

Vector3<Quantity<Meter> > Phyth::Mechanics::Particle::position_

protected

Definition at line 202 of file Particle.hpp.

◆ velocity_

Vector3<Quantity<MeterPerSecond> > Phyth::Mechanics::Particle::velocity_ {}

protected

Definition at line 198 of file Particle.hpp.

The documentation for this class was generated from the following file:

include/Phyth/Elements/Mechanics/Particle.hpp

Public Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Particle()

◆ ~Particle()

Member Function Documentation

◆ ApplyForce()

◆ GetExternalForce()

◆ GetKineticEnergy()

◆ GetMass()

◆ GetPosition()

◆ GetPotentialEnergy()

◆ GetTotalEnergy()

◆ GetVelocity()

◆ Integrate()

◆ IsFixed()

◆ SetComputeForcesFunction()

◆ SetExternalForce()

◆ SetFixed()

◆ SetMass()

◆ SetPosition()

◆ SetVelocity()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ compute_forces_func_

◆ external_force_

◆ fixed_

◆ mass_

◆ position_

◆ velocity_