ollin-py 1.0.0

An object-oriented framework for computational physics education

Ollin

An object-oriented framework for computational physics education and research

Named after the Nahuatl word for dynamic change and transformation

---

The Correspondence Principle

There exists a structural correspondence between physical systems and objects in the OOP paradigm, and making this correspondence explicit provides a useful pedagogical framework for teaching computational physics.

Physical concept	OOP concept	Level
Physical system	class	General
System instance	object	General
Physical parameter	attribute	General
Physical law	method	General
Universality of laws	polymorphism	General
ODE dynamics du/dt = f(u,t)	ODESystem + __call__	ODE
Time evolution	Solver	ODE
Numerical algorithm	Integrator	ODE

---

Installation

pip install ollin

For development:

git clone https://github.com/yoltia/ollin
cd ollin
pip install -e ".[dev]"

---

Quick Start

from ollin.core import Solver, RungeKutta4
from ollin.systems.mechanics.pendulum import NonlinearPendulum
import numpy as np

# Physical system as a class
pendulum = NonlinearPendulum(g=9.81, l=1.0, m=0.5)

# Numerical method chosen independently
solver = Solver(RungeKutta4())

# Raw NumPy arrays — full control
t, u = solver.solve(pendulum, u0=[np.pi/4, 0.0], t0=0, tf=10, h=0.01)
theta = u[:, 0]   # angle [rad]
omega = u[:, 1]   # angular velocity [rad/s]

The same solver works with any physical system:

# Polymorphism: one solver, any physics
t, u = solver.solve(RLCCircuit(R=1, L=1, C=0.25), u0=[1, 0], ...)
t, u = solver.solve(LorenzAttractor(),             u0=[1, 1, 1], ...)
t, u = solver.solve(ThreeBodyProblem(Ms, Mj, Me),  u0=[...], ...)

---

Package Structure

ollin/
├── core/                 -- Framework core
│   ├── system.py         -- PhysicalSystem + ODESystem (abstract base classes)
│   ├── solver.py         -- Solver
│   └── integrators.py    -- Euler, EulerCromer, Verlet, RungeKutta4
│
├── systems/              -- Physical systems by domain
│   ├── mechanics/        -- MRU, MRUA, friction, projectile, pendulums
│   ├── gravity/          -- Planetary orbits, Kepler, N-body
│   ├── circuits/         -- RC, RLC
│   ├── nonlinear/        -- Lorenz attractor
│   ├── nuclear/          -- Radioactive decay
│   ├── stochastic/       -- Random walks, Monte Carlo, stochastic decay
│   ├── molecular/        -- Lennard-Jones MD simulation
│   ├── variational/      -- Fermat's principle
│   ├── condensed/        -- Tight-binding, SSH, Graphene
│   └── quantum/          -- 1D Schrödinger equation
│
├── numerical/            -- Mathematical tools
│   ├── integration.py    -- Riemann, Midpoint, Trapeze, Simpson, Monte Carlo
│   ├── differentiation.py-- Forward, Backward, Central differences
│   └── equations.py      -- Bisection, Newton-Raphson, Secant
│
├── visualization/        -- Plotting utilities (separated from physics)
├── apps/                 -- Interactive tkinter/plotly applications
├── examples/             -- Minimal working examples
└── lab/                  -- Jupyter notebooks for exploration

---

The Two-Level Hierarchy

class PhysicalSystem(ABC):
    """General: ANY physical system.
    Identity + state + dynamics -> class + attributes + methods."""
    pass

class ODESystem(PhysicalSystem):
    """ODE specialization: du/dt = f(u, t).
    Works with any Solver and any Integrator."""
    @abstractmethod
    def __call__(self, u, t): pass

ODESystem subclasses (mechanics, circuits, gravity, chaos) → use the Solver–Integrator pipeline.

PhysicalSystem subclasses (quantum, molecular, stochastic, condensed) → define their own interface appropriate to their mathematical structure.

---

Available Systems

Module	Systems	Base class
mechanics	SimplePendulum, NonlinearPendulum, DampedPendulum, ForcedPendulum, UniformMotion, ProjectileMotion, FrictionMotion	ODESystem
gravity	PlanetaryOrbit, EllipticalOrbit, TwoBodyProblem, ThreeBodyProblem	ODESystem
circuits	RCCircuit, RLCCircuit	ODESystem
nonlinear	LorenzAttractor	ODESystem
nuclear	RadioactiveDecay	ODESystem
quantum	Quantum1D	PhysicalSystem
molecular	LennardJones, MolecularDynamics2D	PhysicalSystem
stochastic	RandomWalk1D, RandomWalk2D, SelfAvoidingWalk, StochasticDecay	PhysicalSystem
condensed	TightBinding, SSH, Graphene	PhysicalSystem
variational	FermatPrinciple	PhysicalSystem

---

Extending Ollin

Adding a new physical system takes exactly four things:

from ollin.core import ODESystem   # or PhysicalSystem for non-ODE

class MySystem(ODESystem):
    def __init__(self, param1, param2):
        self.param1 = param1   # physical parameter as attribute
        self.param2 = param2

    def __call__(self, u, t):  # equation of motion as method
        # return du/dt
        return [...]

# That's it. Works with any Solver and any Integrator.
t, u = Solver(RungeKutta4()).solve(MySystem(p1, p2), u0, t0, tf, h)

---

Running Tests

pytest tests/ -v

Expected: 38 passed.

---

Citation

@misc{ollin2026,
  author       = {S\'anchez-Gonz\'alez, Luis E.},
  title        = {{Ollin}: An object-oriented framework for computational physics},
  howpublished = {\url{https://github.com/yoltia/ollin}},
  year         = {2026}
}

---

Part of the Yoltia Project

Ollin is part of Yoltia: open-source tools for computational physics education and research, developed at Universidad Autónoma de Coahuila, México.

---

License

License. See LICENSE for details.