Metadata-Version: 2.4
Name: brane-skyrmion
Version: 0.1.0
Summary: Physics-Informed Neural Network library for simulating and quantizing topological solitons (Brane-Skyrmions) in braneworld scenarios.
License: MIT
Project-URL: Homepage, https://github.com/kuslavicek/brane-skyrmion
Project-URL: Repository, https://github.com/kuslavicek/brane-skyrmion
Project-URL: Bug Tracker, https://github.com/kuslavicek/brane-skyrmion/issues
Keywords: physics,pinn,soliton,skyrmion,braneworld,topological-solitons,deep-learning,pytorch,differential-geometry,quantization,computational-physics,hep-th
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# brane-skyrmion

> **Physics-Informed Neural Networks for Topological Solitons in Braneworld Scenarios**

[![PyPI version](https://badge.fury.io/py/brane-skyrmion.svg)](https://pypi.org/project/brane-skyrmion/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![arXiv](https://img.shields.io/badge/arXiv-2606.20066-b31b1b.svg)](https://arxiv.org/abs/2606.20066)

`brane-skyrmion` is a Python library for **simulating, minimizing, and quantizing topological solitons** (Brane-Skyrmions) in higher-dimensional braneworld scenarios. Instead of manually deriving and solving complex non-linear differential equations, it uses **Physics-Informed Neural Networks (PINNs)** to variationally minimize the energy functional directly — letting PyTorch's automatic differentiation handle the heavy lifting.

---

## Based On

This library implements the framework introduced in:

> **Quantization of Brane-Skyrmions via Physics-Informed Neural Networks**
> Jose A. R. Cembranos, Alberto García Martín-Caro, Sergio S. Rentero
> [arXiv:2606.20066 [hep-th]](https://arxiv.org/abs/2606.20066) — 14 pages, 3 figures

> In this work, we investigate the canonical quantization of topological solitons appearing in
> braneworld scenarios. In particular, we focus on Brane-Skyrmions, topological field configurations
> analogous to standard Skyrmions, which emerge as solutions of the Dirac-Nambu-Goto action
> supplemented by an induced curvature term. By quantizing the (iso)spin collective coordinates of
> the Brane-Skyrmion, we obtain a Hamiltonian that we solve perturbatively via an expansion in
> powers of J^2, in contrast to the standard Skyrme model. Furthermore, we implement a
> Physics-Informed Neural Network (PINN) to determine the soliton profile that minimizes the energy,
> consistently incorporating the backreaction from the quantized spin degrees of freedom. We conclude
> with a discussion of the potential applications of this framework to the description of hadronic
> spectra. Our results highlight both the theoretical potential of brane-defect models and the
> growing role of neural network methods in theoretical physics.

`brane-skyrmion` is an independent, unaffiliated software implementation of the methods described in
that paper.

---

## What Is a Brane-Skyrmion?

In braneworld physics, particles like protons and neutrons can be modeled as stable topological "knots" in a field living on a membrane (brane) embedded in a higher-dimensional bulk spacetime. These **Brane-Skyrmions** are characterized by a conserved **topological winding number** (baryon number) and their mass/size are governed by a complex geometric action involving the induced worldvolume metric and Ricci scalar curvature.

Computing these properties analytically is notoriously difficult (the Ricci scalar alone requires Mathematica-level symbolic computation). `brane-skyrmion` bypasses this by treating energy minimization as a neural network training problem.

---

## Features

### 1. Automated Differential Geometry Pipeline
Computes the **induced worldvolume metric tensor** `g_μν`, the **Ricci scalar curvature** `R`, and the **invariant volume element** `√(-g)` directly from the soliton profile — fully differentiable via PyTorch autograd.

### 2. Hard-Boundary Topological Ansatz Layer
Implements the architectural constraint `F(r) = F₀(r) + V(r)·N(r)` that **mathematically guarantees** the topological boundary conditions `F(0) = n_W·π` and `F(∞) = 0`. The winding number is preserved by construction — no soft penalty terms needed.

### 3. Variational Energy Minimizer (PINN)
The `BraneSkyrmionPINN` network directly minimizes the **integral energy functional** (not a PDE residual). It uses GELU activations for smooth second-order differentiability and includes a built-in `compute_static_soliton_mass_energy_M_S()` loss function.

### 4. Collective Coordinate Quantizer
Automates the **rigid-rotation quantization** procedure: computes the moment-of-inertia coefficient β, performs the Legendre transformation to canonical angular momentum J, and generates the perturbative **Hamiltonian series** H₀ + H₂·j(j+1) + H₄·j²(j+1)² + …

### 5. Phenomenological Parameter Fitter
Maps the PINN's dimensionless output to **physical hadronic observables** by fitting the brane tension `f` and characteristic size `R_B` to empirical nucleon mass and radius data. Predicts the Nucleon (j=½) and Delta resonance (j=³⁄₂) masses.

### 6. Baryonic Density & RMS Radius Calculator
Computes the **topological baryon density** `ρ_B(r)` and the **isoscalar RMS radius** `⟨r²⟩^½` from the soliton profile, providing direct comparison against experimental measurements.

---

## Installation

### From PyPI

```bash
pip install brane-skyrmion
```

### From Source (Editable / Development)

```bash
git clone https://github.com/kuslavicek/brane-skyrmion.git
cd brane-skyrmion
pip install -e ".[dev]"
```

> **Note**: Requires Python ≥ 3.9 and PyTorch ≥ 2.0. For GPU support, install the appropriate CUDA-enabled PyTorch build from [pytorch.org](https://pytorch.org/get-started/locally/).

---

## Usage

### Quick Start: Static Soliton Energy Minimization

```python
import torch
from brane_skyrmion import BraneSkyrmionPINN

# 1. Define the radial grid (avoiding r=0 for numerical stability)
r = torch.linspace(1e-4, 10.0, 500, requires_grad=True, dtype=torch.float64)

# 2. Instantiate the PINN
pinn = BraneSkyrmionPINN(input_dim=1, hidden_layers=[64, 64, 64], output_dim=1)
optimizer = torch.optim.Adam(pinn.parameters(), lr=1e-3)

# 3. Minimize the static soliton mass/energy functional M_S
for epoch in range(1000):
    optimizer.zero_grad()
    M_S = pinn.compute_static_soliton_mass_energy_M_S(r)
    M_S.backward()
    optimizer.step()
    if epoch % 100 == 0:
        print(f"Epoch {epoch:4d} | M_S = {M_S.item():.6f}")
```

### Constructing the Soliton Profile

```python
from brane_skyrmion import (
    atiyah_manton_profile,
    construct_hedgehog_soliton_profile_F_r,
)

# Atiyah-Manton analytical ansatz (good initial guess)
F_0 = atiyah_manton_profile(r, characteristic_soliton_size_scale_R_B=1.0)

# Topologically constrained profile from PINN output
N_r = pinn(r.unsqueeze(-1)).squeeze(-1)
F_r = construct_hedgehog_soliton_profile_F_r(r, N_r, n_W=1, r_max=10.0)
```

### Geometry: Metric Tensor & Curvature

```python
from brane_skyrmion import (
    compute_induced_worldvolume_metric_tensor_g_mu_nu,
    compute_ricci_scalar_curvature_R,
    compute_invariant_volume_element,
)

g_mu_nu = compute_induced_worldvolume_metric_tensor_g_mu_nu(r, F_r)  # [N, 4, 4]
R       = compute_ricci_scalar_curvature_R(r, F_r)                   # [N]
sqrt_g  = compute_invariant_volume_element(r, F_r)                   # [N]
```

### Quantization: Nucleon & Delta Resonance Masses

```python
from brane_skyrmion import (
    compute_quantum_hamiltonian_series,
    compute_quantum_energy_eigenvalue,
)

H_series = compute_quantum_hamiltonian_series(r, F_r, max_order=4)

E_nucleon = compute_quantum_energy_eigenvalue(r, F_r, j=0.5)   # Nucleon
E_delta   = compute_quantum_energy_eigenvalue(r, F_r, j=1.5)   # Delta resonance

print(f"Nucleon energy : {E_nucleon.item():.4f}")
print(f"Delta  energy  : {E_delta.item():.4f}")
assert E_delta > E_nucleon  # Delta is heavier — centrifugal barrier
```

### Phenomenology: Fit to Experimental Data

```python
from brane_skyrmion import fit_phenomenological_parameters

params = fit_phenomenological_parameters(
    empirical_nucleon_mass_M_N=939.0,   # MeV
    empirical_nucleon_radius_r_N=0.72,  # fm
    lambda_star=0.8,
)
print(params)  # {'f': ..., 'R_B': ..., 'J_star': ...}
```

---

## Module Reference

| Module | Key Exports | Purpose |
|--------|-------------|---------|
| `geometry` | `compute_induced_worldvolume_metric_tensor_g_mu_nu` | Induced metric `g_μν` from profile `F(r)` |
| `geometry` | `compute_ricci_scalar_curvature_R` | Ricci scalar `R` via finite differences |
| `geometry` | `compute_invariant_volume_element` | `√(-g)` for action integration |
| `ansatz` | `atiyah_manton_profile` | Analytical Atiyah-Manton profile `F₀(r)` |
| `ansatz` | `boundary_enforcement_weight_V_r` | Bump function `V(r)` vanishing at boundaries |
| `ansatz` | `construct_hedgehog_soliton_profile_F_r` | Hard-constrained profile `F(r) = F₀ + V·N` |
| `pinn` | `BraneSkyrmionPINN` | PINN module; minimizes `M_S` as loss |
| `quantization` | `compute_lagrangian_expansion_coefficient_beta` | Moment-of-inertia coefficient β |
| `quantization` | `compute_canonical_angular_momentum_J` | Canonical angular momentum `J = β·ω` |
| `quantization` | `compute_quantum_hamiltonian_series` | Hamiltonian coefficients `[H₀, H₂, H₄]` |
| `quantization` | `compute_quantum_energy_eigenvalue` | Energy eigenvalue `E_j = H₀ + H₂·j(j+1) + …` |
| `phenomenology` | `compute_baryonic_topological_density_rho_B_r` | Baryon density `ρ_B(r)` |
| `phenomenology` | `compute_isoscalar_rms_radius` | Isoscalar RMS radius `⟨r²⟩^½` |
| `phenomenology` | `fit_phenomenological_parameters` | Fit `f`, `R_B` to hadronic data |

---

## Symbol → Code Mapping

| Math Symbol | Python Name | Type |
|-------------|-------------|------|
| `g_μν` | `induced_worldvolume_metric_tensor_g_mu_nu` | `Tensor [N, 4, 4]` |
| `F(r)` | `hedgehog_soliton_profile_F_r` | `Tensor [N]`, `F(0)=n_W·π`, `F(∞)=0` |
| `N(r)` | `pinn_neural_network_output_N_r` | `Tensor [N]`, unconstrained |
| `V(r)` | `boundary_enforcement_weight_V_r` | `Tensor [N]`, `V(0)=V(r_max)=0` |
| `n_W` | `topological_winding_number_n_W` | `int`, baryon number |
| `β` | `lagrangian_expansion_coefficient_beta` | `Tensor` scalar, moment of inertia |
| `j` | `quantum_angular_momentum_number_j` | `float`, spin quantum number |
| `ρ_B(r)` | `baryonic_topological_density_rho_B_r` | `Tensor [N]`, `∫ρ_B dr = n_W` |

---

## Running Tests

```bash
pytest tests/ -v
```

All 6 test modules cover geometry, ansatz, PINN forward/backward passes, quantization, phenomenology, and end-to-end integration.

---

## Contributing

Contributions, bug reports, and feature requests are welcome! Please open an issue or pull request on [GitHub](https://github.com/kuslavicek/brane-skyrmion).

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Install in editable mode: `pip install -e ".[dev]"`
4. Run tests: `pytest`
5. Submit a pull request

---

## License

This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.

---

## Citation

If you use `brane-skyrmion` in academic work, please cite the underlying paper:

```bibtex
@article{Cembranos:2026braneskyrmion,
  title         = {Quantization of Brane-Skyrmions via Physics-Informed Neural Networks},
  author        = {Cembranos, Jose A. R. and Garc\'ia Mart\'in-Caro, Alberto and Rentero, Sergio S.},
  year          = {2026},
  eprint        = {2606.20066},
  archivePrefix = {arXiv},
  primaryClass  = {hep-th},
  doi           = {10.48550/arXiv.2606.20066},
}
```
