This repository investigates a physical hypothesis about floating bodies on water.
Hypothesis under investigation:
When two elongated floating bodies on water fall below a certain lateral distance, they tend to move toward each other because fewer wave events exert pressure on their inner sides than on their outer sides. This creates a net inward force and may eventually lead to side contact.
This hypothesis must not be assumed true. All work in this repository must preserve the ability to confirm, weaken, or falsify it.
The project is exploratory and research-oriented, not demonstrative propaganda for a preferred conclusion.
- Build a scientifically useful simulation framework for the hypothesis.
- Start with a reduced, interpretable model before adding more realism.
- Make all assumptions explicit.
- Measure observables that can distinguish between:
- fewer inner-side wave hits
- lower cumulative inner-side impulse
- purely geometric shielding
- model artifacts
- alternative explanations
- Keep the code and notebook structure suitable for later extension.
Start with a 2D top-view event-based Monte Carlo simulation.
Use:
- two elongated floating bodies
- simple geometry (rectangles or capsules)
- stochastic wave events distributed in space
- a simplified attenuation law
- a directional contribution model for side pressure / impulse
- explicit logging of inner-side and outer-side hits and impulses
Do not start with:
- full CFD
- Navier-Stokes solvers
- high-complexity fluid packages
- visually impressive but conceptually opaque simulations
Only after the minimal model works and is interpretable, a more advanced wave-field model may be added.
Possible later additions:
- non-parallel body orientations
- body rotation
- reflection / partial reflection
- interference effects
- current / drift terms
- capillary effects for small objects
- empirical calibration if data becomes available
All implementations must follow these rules:
- Do not bake the desired conclusion into the mechanics.
- Prefer transparent and falsifiable logic over realism theater.
- State assumptions explicitly in code comments and notebooks.
- Make parameter choices visible and easy to vary.
- Record enough intermediate metrics to inspect why an effect appears.
- When results are ambiguous, say so.
- When a result depends strongly on a modeling choice, document that dependency.
- Distinguish clearly between:
- observation
- model assumption
- inference
- speculation
Before making substantial changes:
- Inspect the repository structure.
- Summarize the intended change briefly.
- Identify affected files.
- Prefer small, coherent commits.
When implementing:
- Keep code modular and typed where practical.
- Prefer simple helper modules over oversized notebooks.
- Keep the notebook readable and explanatory.
- Use deterministic seeds where possible.
After implementing:
- Summarize what changed.
- Summarize assumptions introduced or modified.
- Note conceptual risks or limitations.
- Suggest the next most sensible step.
The main notebook should usually contain:
- Problem statement
- Reformulated hypothesis
- Why this modeling level was chosen
- Mathematical or algorithmic assumptions
- Simulation design
- Observables / metrics
- Experiments
- Visualizations
- Interpretation
- Alternative explanations / confounders
- Limitations
- Next steps
The notebook must be understandable without reading the entire codebase.
Use Python. Prefer:
dataclasses- type hints
- small pure functions where possible
- NumPy for vectorized work
- Matplotlib for clear plots
Avoid:
- unnecessary frameworks
- hidden state
- magic constants without explanation
- premature optimization
- decorative abstractions with no analytical value
Performance matters only after correctness and interpretability.
Do not write smoke tests as a substitute for real tests.
- Write tests that fail for incorrect behavior, fragile assumptions, regressions, and unsafe handling.
- Prefer edge cases, adversarial inputs, and boundaries over happy paths.
- Assert exact behavior, invariants, error contracts, and state transitions.
- Test malformed, missing, duplicated, oversized, and unexpected input.
- Use pytest.parametrize for boundary matrices.
- Use pytest.raises for precise failure semantics.
- Add regression tests for discovered bugs.
- Use Hypothesis only for meaningful invariants and properties.
- Test repeated calls, idempotency, mutation, stale state, and ordering dependence where relevant.
- Test security-relevant abuse cases where applicable.
- Mock only external boundaries, not internal logic.
- State for each nontrivial test what it is intended to catch.
A test that only proves “no exception was raised” is insufficient.
If the code is hard to test, name the design limitation explicitly.
Use clear technical English. Be precise, restrained, and explicit about uncertainty. Do not overclaim physical truth from a toy model. Do not describe results as “proof” unless they actually justify that level of certainty.
If the minimal model does not show a robust effect, do not blindly add complexity just to recover the desired outcome. Instead:
- inspect assumptions
- test alternative source distributions
- test whether the hypothesis formulation itself needs revision
If the minimal model does show an effect, the next step is not celebration but robustness analysis.
The current priority is to create the first well-structured Jupyter notebook implementing the minimal event-based 2D Monte Carlo model.