-> Download the latest version of Masscience from the /Releases section by clicking here!
A privacy-first, client-side lean bulk & mini-cut companion built around bodyweight trends instead of obsessive calorie tracking.
🚀 Try Masscience · 📖 Documentation · 🧮 Algorithms · 🤝 Contributing
Masscience is a data-driven bodyweight and nutrition management application designed for people who want to gain muscle while keeping unnecessary fat gain under control.
Traditional bulking often creates two extremes:
"I'll just eat everything and hope I gain muscle."
or:
"I need to weigh every ingredient of every meal."
Masscience takes a different approach.
You don't necessarily need to know exactly how many calories you ate. You need to know how your body is responding.
Masscience observes the user's bodyweight trajectory and uses that information to estimate whether the current calorie target is producing the desired rate of gain.
USER PROFILE
│
▼
┌───────────────────┐
│ Initial Estimates │
│ BMR / TDEE / BF │
└─────────┬─────────┘
│
▼
LEAN BULK START
│
▼
┌───────────────────┐
│ Weight Collection │
│ + Trend Analysis │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Rate of Gain │
│ kg/week │
│ % BW/week │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Control Engine │
│ │
│ Is the trajectory │
│ on target? │
└─────────┬─────────┘
│
┌──────┴──────┐
▼ ▼
ON TARGET OFF TARGET
│ │
│ ▼
│ Adjust Calories
│
└──────┬──────┘
▼
CONTINUE
│
▼
BULK PROJECTION
│
▼
MINI-CUT
│
▼
REPEAT
The user does not need to understand the mathematics behind this system.
Masscience handles the calculations.
PS C:\Users\wesle\Documents\Masscience> python linesofcode.py
============================================================
CODE LINE COUNTER
============================================================
JavaScript 49 files 12,682 lines
JSON 8 files 11,680 lines
Markdown 11 files 2,920 lines
CSS 2 files 1,481 lines
XML 12 files 303 lines
Batch 2 files 237 lines
Python 1 file 137 lines
PowerShell 1 file 49 lines
Shell 1 file 44 lines
Java 3 files 38 lines
HTML 2 files 36 lines
TypeScript 1 file 7 lines
------------------------------------------------------------
TOTAL 93 files 29,614 lines
============================================================
Masscience uses a default cycle of:
10 weeks — Lean Bulk
↓
3 weeks — Mini-Cut
↓
Repeat
Initial calorie targets:
| Phase | Target |
|---|---|
| Lean Bulk | TDEE + 300 kcal |
| Mini-Cut | TDEE − 500 kcal |
The system can adapt the calorie target based on observed weight trajectory.
One of the main goals of Masscience is to reduce the annoyance of constant weighing.
Instead of requiring daily measurements indefinitely, the application progressively reduces the frequency when enough evidence exists.
┌────────────────────┐
│ First 10 days │
│ DAILY │
└─────────┬──────────┘
↓
┌────────────────────┐
│ Every other day │
└─────────┬──────────┘
↓
┌────────────────────┐
│ 3× per week │
└─────────┬──────────┘
↓
Maintain
If the trend becomes unreliable, Masscience can increase measurement frequency again.
When a measurement is missing, Masscience can estimate the expected weight using the current trend.
Estimated values are explicitly marked as:
ESTIMATED
They are never presented as actual measurements.
Daily bodyweight is noisy.
A person can gain or lose more than a kilogram without meaningfully changing their body composition.
Masscience therefore analyzes the trend, rather than reacting to individual measurements.
The trend engine accounts for:
- day-to-day noise
- outliers
- measurement frequency
- rolling observation windows
- regression
- trend confidence
- rate of change
Primary metrics:
Current weight
Trend weight
Rate of gain
% bodyweight/week
Trend confidence
Masscience does not simply tell everyone:
Gain 0.2 kg/week.
Instead, its primary target is expressed relative to bodyweight:
% bodyweight / week
This makes the target scale between users.
The target can be influenced by:
- bodyweight
- training age
- current BF estimate
- training frequency
The objective is a conservative bulk with enough progression to support muscle gain while avoiding unnecessarily aggressive weight gain.
Masscience starts with an estimated TDEE:
BMR × Activity Factor
As the user accumulates data, the application can infer an effective TDEE from:
Observed weight change
+
Calorie target
+
Time
The system intentionally distinguishes between:
Calories prescribed
and:
Calories actually consumed
If the user does not log their food intake, Masscience cannot know their exact intake.
Therefore TDEE is presented as an estimate with uncertainty.
Masscience estimates:
- Body-fat %
- Fat mass
- Lean mass
- FFMI
Possible inputs include:
- initial user estimate
- waist circumference
- neck circumference
- height
- bodyweight
The application can use the U.S. Navy body-fat equation when appropriate.
Lean Mass ≠ Muscle Mass
Lean mass contains water and other non-fat tissues in addition to skeletal muscle.
Masscience does not pretend that an estimated increase in lean mass is an exact measurement of muscle growth.
Masscience can simulate possible outcomes for the end of a cycle.
Instead of producing:
You WILL weigh 68.4 kg.
it produces an estimated distribution:
Expected weight
16% 50% 84%
│ │ │
▼ ▼ ▼
67.2 68.0 68.9 kg
The projection engine uses Monte Carlo simulation to model uncertainty in future trajectories.
Possible outputs include:
- projected weight
- projected BF
- projected lean mass
- projected fat mass
- projected FFMI
- trajectory risk
Masscience uses a conservative feedback-control system.
TARGET RATE
│
▼
┌───────────────┐
│ Compare with │
│ actual trend │
└───────┬───────┘
│
▼
RATE ERROR
│
▼
CONFIDENCE
│
▼
┌───────────────┐
│ Controller │
│ + Deadband │
│ + Cooldown │
└───────┬───────┘
│
▼
CALORIE ADJUSTMENT
The controller deliberately avoids making large changes based on a single noisy measurement.
It uses:
- rate error
- trajectory error
- confidence
- deadband
- minimum evidence
- discrete adjustment steps
- cooldown periods
Masscience does not use one giant "accuracy score."
Different parts of the system have different uncertainty.
Therefore it maintains separate confidence concepts:
| Metric | Meaning |
|---|---|
| Trend Confidence | How reliable the observed weight trend is |
| TDEE Confidence | How much evidence supports the TDEE estimate |
| BF Confidence | Confidence in body-fat estimation |
| Projection Confidence | Confidence in future trajectory |
This allows the application to communicate uncertainty honestly.
Current algorithm version:
2.1.0
Masscience's mathematical engine is modular.
js/
├── calculations.js
├── trend.js
├── composition.js
├── control.js
├── adaptive.js
├── projection.js
├── confidence.js
├── cycle.js
└── storage.js
Current approach:
Rolling OLS
+
Outlier downweighting
+
Adaptive observation window
Current approach:
User BF estimate
+
Navy method
+
BF inertia
+
Uncertainty propagation
Current approach:
Weight trajectory
+
Rate error
+
Trajectory error
+
Confidence
+
Deadband
+
Cooldown
Current approach:
Monte Carlo
+
Truncated-normal rate distribution
+
Uncertainty propagation
Masscience treats its mathematical model as a first-class part of the project.
Every major algorithm should be:
- documented
- testable
- benchmarkable
- replaceable
- versioned
Algorithm changes are recorded in:
ALGORITHM_CHANGELOG.md
Complete mathematical documentation:
ARCHITECTURE.md
Build architecture:
BUILD_ARCHITECTURE.md
| Platform | Technology | Output | Offline |
|---|---|---|---|
| 🌐 Web | HTML/CSS/JS | Web App | ✅ |
| 🪟 Windows | Electron | .exe |
✅ |
| 🐧 Linux | Electron | .AppImage |
✅ |
| 🤖 Android | Capacitor | .apk |
✅ |
The same frontend is reused across all platforms.
HTML
│
CSS + JavaScript
│
┌───────────┼───────────┐
│ │ │
Web Electron Capacitor
│ │ │
▼ ┌───┴───┐ ▼
Browser Win Linux Android
No account required.
No backend required.
No installation required.
Simply open the deployed GitHub Pages application.
Or run locally:
git clone https://github.com/wesleyyan-sb/masscience.git
cd masscience
npm ci
npm run devMasscience includes an automated build system.
On Windows:
build.batOne command can build:
Windows installer
Linux AppImage
Android APK
Web build
Individual targets can also be built:
build.bat windows
build.bat linux
build.bat android
build.bat webMore information:
BUILD.md
Masscience is designed around reproducible builds.
Developer
│
▼
build.bat
│
├───────────────┐
▼ ▼
Web Build Electron
│
┌─────┴─────┐
▼ ▼
Windows Linux
│ │
.exe .AppImage
Capacitor
│
▼
Android
│
.apk
GitHub Actions can also generate platform artifacts automatically.
Masscience is designed to be client-side and privacy-first.
Your data can remain entirely on your device.
There is no required:
- account
- backend
- cloud database
- telemetry server
- external AI
- nutrition API
- subscription
The application can work offline.
Your:
Weight
BF estimates
Measurements
Calories
Cycle history
Projections
do not need to leave your device.
Core functionality is designed to work without an internet connection.
Offline functionality includes:
- weight tracking
- trend analysis
- BF estimation
- TDEE estimation
- calorie recommendations
- projections
- Monte Carlo simulations
- charts
- local persistence
- cycle management
Internet access is primarily useful for things such as downloading the application or accessing the web deployment.
Run the regression suite:
node js/tests/run-tests.jsTrend benchmark:
node js/tests/benchmark-trend.jsMonte Carlo benchmark:
node js/tests/benchmark-mc.jsThe test suite covers areas such as:
- trend calculations
- outlier detection
- missing measurements
- BF inertia
- controller behavior
- Monte Carlo convergence
- cycle transitions
- projection behavior
- Lean bulk cycle
- Mini-cut cycle
- Weight tracking
- Trend analysis
- Adaptive calorie control
- BF estimation
- FFMI estimation
- Cycle projections
- Monte Carlo projections
- Confidence system
- Smart weigh-in frequency
- Web
- Windows
- Linux
- Android
- Automated builds
- Automated signed releases
- Progressive overload tracking
- Training integration
- Optional food tracking
- Better water/glycogen event detection
- Improved uncertainty calibration
- Additional body-composition models
- Expanded benchmark datasets
- iOS support
- More detailed analytics
- Import/export improvements
Masscience is open source and contributions are welcome.
You can contribute with:
- frontend
- algorithms
- performance
- desktop
- Android
- testing
- build infrastructure
Particularly valuable contributions include:
- better trend estimators
- better TDEE models
- better body-composition estimation
- improved uncertainty modeling
- improved projection distributions
- real-world benchmark datasets
- UI/UX
- accessibility
- responsive layouts
- mobile experience
- visualization
- algorithm explanations
- examples
- translations
- tutorials
Masscience cannot know with certainty:
- exact TDEE
- exact calorie intake without logging
- exact body-fat percentage
- exact muscle gain
- exact nutrient partitioning
- exact future weight
- exact metabolic adaptation
Human physiology is noisy and highly individual.
The application's projections are model-based estimates, not guarantees.
Masscience is an informational and educational tool.
It is not a substitute for individualized advice from a qualified healthcare or nutrition professional.
The application should not be used as the sole basis for medical or nutritional decisions.
Masscience is open source.
See LICENSE for the complete license.
Masscience exists because building muscle shouldn't require turning your life into a spreadsheet.
You shouldn't necessarily have to:
weigh every ingredient
+
track every meal
+
panic over daily weight fluctuations
Instead:
Train
↓
Eat
↓
Measure
↓
Observe the trend
↓
Adjust
↓
Repeat
The goal isn't perfect prediction.
The goal is better decisions from imperfect data.
