Metadata-Version: 2.4
Name: sinusoidalnn
Version: 1.0.0
Summary: TensorFlow-based Sinusoidal Neural Network for signal decomposition, spectral analysis, and signal reconstruction
Author: Jovan
License: MIT License
        
        Copyright (c) 2026 Jovan-AIcoder
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/jovan-AIcoder/SinusoidalNN
Project-URL: Issues, https://github.com/jovan-AIcoder/SinusoidalNN/issues
Keywords: signal-processing,neural-network,tensorflow,fourier-analysis,spectrum-analysis,spectral-analysis
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: tensorflow
Dynamic: license-file

# SinusoidalNN

![logo](https://raw.githubusercontent.com/jovan-AIcoder/SinusoidalNN/main/logo.png)

A TensorFlow-based Sinusoidal Neural Network (SNN) for signal decomposition, spectral analysis, and signal reconstruction.

---

## Overview

SinusoidalNN is a Python package that represents a signal as a trainable superposition of sinusoidal components.

Instead of using a conventional Fourier Transform, SinusoidalNN learns frequencies, amplitudes, and phase shifts directly through gradient descent using TensorFlow.

Signal representation:

```text
y(t) = Σ Ai sin(2πfi t + φi)
```

where:

- fi = learned frequency
- Ai = learned amplitude
- φi = learned phase shift

The package provides:

- Signal fitting
- Spectrum extraction
- Signal reconstruction
- Model saving and loading
- Signal preprocessing
- TensorFlow optimizer support

---

## Installation

```bash
pip install sinusoidalnn
```

---

# Try the Demo First

Before writing any code, it is recommended to explore the example project.

Inside the repository:

```text
examples/

├── demo.py
├── signal_original.csv
```

Run:

```bash
python demo.py
```

The demo will:

1. Load a signal from CSV
2. Train a SinusoidalNN model
3. Save the trained model
4. Extract the learned spectrum
5. Plot the spectrum
6. Reconstruct the signal
7. Save the reconstructed signal

Generated files:

```text
model_demo.h5

spectrum.csv
spectrum.png

signal_reconstructed.csv

signal_comparison.png
```

This is the fastest way to understand how SinusoidalNN works.

---

## Quick Start

### Import Package

```python
from sinusoidalnn import SNN
```

---

### Load Signal

```python
import pandas as pd

df = pd.read_csv("signal.csv")

t = df["Time"]
y = df["Signal"]
```

---

### Create Model

```python
snn = SNN(
    max_modes=1000,
    optimizer="adam",
    learning_rate=1e-4,
    verbose=1
)
```

---

### Fit Signal

```python
snn.fit_signal(
    t,
    y,
    epochs=256
)
```

---

### Extract Spectrum

```python
spectrum = snn.return_spectrum()
```

Example:

```text
   Frequencies  Phase shift  Amplitudes
0      49.99       0.12        0.998
1     120.03      -0.31        0.502
...
```

---

### Reconstruct Signal

```python
signal = snn.reconstruct_signal(
    duration=1.0,
    sample_rate=1000
)
```

Output:

```text
       Time    Signal
0    0.0000   0.0123
1    0.0010   0.5234
...
```

---

## Save Model

```python
snn.save_model(
    "my_model.h5"
)
```

---

## Load Model

```python
snn.load_SNN_model(
    "my_model.h5"
)
```

---

## Signal Preprocessing

### Baseline Removal

```python
from sinusoidalnn import zeroing_baseline

y = zeroing_baseline(y)
```

Removes DC offset from a signal by subtracting its mean value.

---

## Supported Optimizers

SinusoidalNN supports:

- SGD
- RMSprop
- Adam
- AdamW
- Adagrad
- Adadelta
- Adamax
- Nadam
- FTRL

Example:

```python
snn = SNN(
    optimizer="adamw"
)
```

---

# API Reference

## SNN

```python
SNN(
    max_modes=10000,
    use_phase_shift=True,
    optimizer="adam",
    learning_rate=1e-4,
    verbose=2
)
```

---

## fit_signal

```python
fit_signal(
    t,
    y,
    epochs=256
)
```

Train the model on a signal.

---

## return_spectrum

```python
return_spectrum(
    positive_freqs_only=True,
    abs_amplitudes=True
)
```

Extract learned frequencies, amplitudes, and phase shifts.

---

## reconstruct_signal

```python
reconstruct_signal(
    duration=5.0,
    sample_rate=44100
)
```

Generate a reconstructed signal using the learned sinusoidal representation.

---

## save_model

```python
save_model(path)
```

Save the TensorFlow model.

---

## load_SNN_model

```python
load_SNN_model(path)
```

Load a previously saved model.

---

## Dependencies

- TensorFlow
- NumPy
- Pandas
- Matplotlib

---

## License

MIT License

---

## Repository

https://github.com/jovan-AIcoder/SinusoidalNN

---

## Author

Jovan

---

## Citation

If you use SinusoidalNN in research, academic work, scientific reports, or publications, please cite the repository and acknowledge the package appropriately.
