Metadata-Version: 2.4
Name: vyom-sutra
Version: 1.0.2
Summary: Fast Universal Similarity-Based Decision Engine
Author: Sanjok Thapa
License: MIT
Keywords: similarity,wave,decision,universal,fast,engine
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Android
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# Vyom Sutra

A wave-based decision engine.

Takes any value and a target.
Returns a similarity score between 0 and 100.

One function. Any sector.

## Install

pip install vyom-sutra

## Quick Start

import vyom_sutra as vyom

r = vyom.score(1.3, target=1.2566, scale=1.0)
print(r['score'])      # 99.91
print(r['verdict'])    # Excellent

## Output

score > 95    excellent
score > 80    clean
score > 50    weak
score < 50    noise

Any score above 80 means the value matches the target.

---

# Priority Sectors

These are the sectors we focus on.
Each has a real use case, code example, and expected result.

---

## 1. Earthquake Detection

A seismometer records ground motion every second.
The raw signal contains earthquakes, traffic, wind,
and machine noise all mixed together.

Earthquake waves have a known shape (a target phase).
Vyom Sutra compares each frequency with that target.
Clean frequencies pass. Noise is dropped.

### How it works

  1. Read the sensor signal.
  2. FFT splits the signal into frequencies.
  3. Vyom scores each frequency against the target.
  4. Frequencies near the target = earthquake.

### Code

import numpy as np
import vyom_sutra as vyom

signal = read_seismometer()          # raw ground motion
spectrum = np.fft.fft(signal)        # split into frequencies

eq_target = 2.0                      # known earthquake phase
hits = 0

for freq in spectrum:
    r = vyom.score(freq, target=eq_target, scale=1.0)
    if r['clean']:
        hits += 1

if hits > 10:
    print("earthquake detected")
else:
    print("no earthquake")

### Result

Real earthquake    ->  10 or more clean frequencies
Traffic or wind    ->  fewer than 10 clean frequencies

### Use case

Separate a real quake from a passing truck,
strong wind, or construction work.
Earlier warning. Fewer false alarms.

---

## 2. Medicine

Screening drug compounds.

Each compound has two numbers:

  MW    molecular weight (size)
  LogP  oiliness (how it dissolves)

These two numbers give a phase angle.
That angle is compared with the target protein angle.

### How it works

  1. Take MW and LogP of a compound.
  2. Compute its phase angle.
  3. Compare with the target protein phase.
  4. If close, the compound is a candidate.

### Code

import vyom_sutra as vyom

mw     = 463.9       # Nazartinib
logp   = 2.8
target = 1.2566      # EGFR protein

phase = (mw / 500) * 1.1 + (logp / 5) * 0.5
r = vyom.score(phase, target=target, scale=1.0)

if r['clean']:
    print("candidate")
else:
    print("reject")

### Result

Nazartinib     ->  score 99.61   candidate
Gefitinib      ->  score 99.57   candidate
Aspirin        ->  score 33.42   reject
Metformin      ->  score  8.42   reject

### Use case

Filter a million compounds down to a short list
for the lab. Save months of time and millions in cost.

---

## 3. Cosmology

Testing a universe model against real data.

For each scale k, the model predicts a value n_s.
Compare with the measured value from Planck 2018.

### How it works

  1. Pick a scale k.
  2. Compute the model n_s.
  3. Compare with measured n_s.
  4. Score tells how close the model is.

### Code

import vyom_sutra as vyom

measured_ns = 0.9649     # Planck 2018

for k in [5, 8, 12, 16]:
    model_ns = 1 - 2/60 + 0.0012 * (k - 5)
    r = vyom.score(model_ns, target=measured_ns, scale=1.0)
    print("k =", k, "score =", r['score'])

### Result

k = 5    score around 96
k = 16   score around 96   (closest to Planck)

### Use case

Check how close a model is to real data.
Fast. No full simulation needed.

---

## 4. Global Warming

Tracking how a temperature signal drifts over time.

Temperature data from a region arrives as a slow wave.
The natural seasonal cycle is one target.
The long term rising trend is a second target.

Vyom Sutra separates the two.
Short cycles are filtered out.
The long trend is kept.

### How it works

  1. Read monthly temperature data.
  2. FFT splits it into cycles.
  3. Score the yearly cycle (target 1.0).
  4. Score the long trend (target 0.05).
  5. Compare two decades.

### Code

import numpy as np
import vyom_sutra as vyom

temps = read_monthly_temps()         # 30 years of data
spectrum = np.fft.fft(temps)

yearly = 0
trend = 0

for freq in spectrum:
    r_year = vyom.score(freq, target=1.0)
    r_trend = vyom.score(freq, target=0.05)

    if r_year['clean']:
        yearly += 1
    if r_trend['clean']:
        trend += 1

print("yearly cycles:", yearly)
print("long term trend:", trend)

### Result

If trend value increases over decades, warming is real.
If yearly cycles are stable, the season is normal.

### Use case

Separate weather from climate.
See a slow warming trend without being distracted
by cold winters or hot summers.

---

## 5. Weather Forecasting

Reading the daily temperature and rainfall cycle.

Weather data has many repeating waves:
daily, weekly, monthly, seasonal.
Some are real patterns. Some are noise.

Vyom scores each wave against the known pattern.
Clean waves are used to build the forecast.

### How it works

  1. Read past temperature and rainfall.
  2. FFT splits into frequencies.
  3. Score against the known weather cycle.
  4. Keep the clean frequencies.
  5. Use them to project the next days.

### Code

import numpy as np
import vyom_sutra as vyom

temp = read_past_temps()             # last 5 years
rain = read_past_rain()

for signal, target in [(temp, 1.0), (rain, 0.5)]:
    spectrum = np.fft.fft(signal)
    clean = 0
    for freq in spectrum:
        r = vyom.score(freq, target=target)
        if r['clean']:
            clean += 1
    print("clean frequencies:", clean)

### Result

Clean pattern -> stable forecast
Noisy pattern -> unstable forecast, low confidence

### Use case

Filter noisy sensor data before running a forecast model.
Drop fake spikes. Keep real trends.

---

# Other Sectors

The same function works anywhere a decision is needed.

## Game NPC

import vyom_sutra as vyom

for npc_id in range(10000):
    r = vyom.score(npc_id * 0.618, target=1.5)
    if r['clean']:
        print("active NPC", npc_id)

## Finance

r = vyom.score(price * 0.001, target=2.0)

## Music

r = vyom.score(frequency / 100.0, target=4.4)

## Audio denoise

FFT + Vyom. Same pattern as earthquake.

## Image compression

DCT + Vyom. Same pattern.

## Terrain height

r = vyom.score(x * 0.3 + y * 0.3, target=1.0)

---

# Dynamic Scale

scale is a multiplier on the difference.
Larger scale means a stricter filter.

scale = 0.5    coarse   (many pass)
scale = 1.0    normal   (default)
scale = 5.0    fine     (fewer pass)
scale = 25.0   very fine

Any value works.

Example:

value = 1.3, target = 1.2566

scale = 1.0    score = 99.91
scale = 5.0    score = 97.65
scale = 25.0   score = 46.69

## When to change scale

Too many results    ->  increase scale
Too few results     ->  decrease scale

Start with 1.0. Change only if needed.

---

# Batch

For large data sets.

values = [i * 0.001 for i in range(1000000)]
results = vyom.score_batch(values, target=1.2566, scale=1.0)

Speed: around 20 million values per second.

---

# License

MIT

Free for everyone. No restrictions.
