Metadata-Version: 2.4
Name: physlang
Version: 0.1.0
Summary: Write math, run code. A DSL for mathematical physics.
Author: David Johnson
License: Apache-2.0
Project-URL: Homepage, https://github.com/dmjdxb/PhysLang
Project-URL: Documentation, https://github.com/dmjdxb/PhysLang
Project-URL: Repository, https://github.com/dmjdxb/PhysLang
Keywords: physics,mathematics,dsl,compiler,scientific-computing,quantum,numpy,jax,latex
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Provides-Extra: jax
Requires-Dist: jax>=0.4.0; extra == "jax"
Requires-Dist: jaxlib>=0.4.0; extra == "jax"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: physlang[dev,jax]; extra == "all"
Dynamic: license-file

# PhysLang

**Write math, run code.**

PhysLang is a domain-specific language that lets you write mathematical notation directly and execute it as Python. No more translation errors between paper and code.

```
> let beta = 1.0
> let mu = U/2
> compute sum(n, 1, 100, n)
  = 5050
> compute integrate(sin(x), x, 0, pi)
  = 2.0
```

## Installation

```bash
pip install physlang
```

**That's it!** The first time you run `physlang`, it automatically:
- Creates a desktop shortcut with the **Ĥ (Hamiltonian)** icon
- Adds PhysLang IDE to your applications menu

### For Students

Just run these two commands:
```bash
pip install physlang
physlang
```

You'll see the Ĥ icon appear on your desktop. Double-click it anytime to open the IDE!

### Manual Desktop Setup

If the automatic setup didn't work, you can run:
```bash
physlang --install     # Add desktop shortcut
physlang --uninstall   # Remove it
```

### Optional: JAX Support

For GPU acceleration and automatic differentiation:

```bash
pip install physlang[jax]
```

## Quick Start

### Command Line

```bash
# Start interactive REPL
physlang

# Execute single expression
physlang -c "sum(n, 1, 100, n)"

# Execute file
physlang program.phi

# Show generated Python
physlang -p -c "integrate(x^2, x, 0, 1)"

# Use JAX backend
physlang -j -c "grad(f, 3.0)"
```

### Web IDE

PhysLang includes a full web-based IDE with symbol palette, real-time translation, and code export:

```bash
# Open the IDE in your browser
physlang --ide

# Or start with a local server (for some browsers)
physlang --ide --serve
```

From Python:
```python
from physlang import launch_ide
launch_ide()
```

The IDE features:
- **Math Editor**: Write with Unicode symbols (α, β, ∑, ∫, ², etc.)
- **Symbol Palette**: Click to insert Greek letters, operators, subscripts/superscripts  
- **Auto-conversion**: Type `\alpha` → α, `^2` → ², `\sum` → ∑
- **Real-time Translation**: See Python/JAX code generated instantly
- **Export**: Download as .txt, .py, or JAX .py
- **Works Offline**: Fully self-contained, no server needed

### Python API

```python
from physlang import run, compile_to_python, compile_to_jax

# Execute directly
result = run("sum(n, 1, 100, n)")  # 5050

# Get Python code
code = compile_to_python("let f(x) = x^2\ncompute f(5)")
print(code)

# Get JAX code (GPU + autodiff)
jax_code = compile_to_jax("let f(x) = x^2\ncompute grad(f, 3.0)")
```

## Typing Math

PhysLang accepts both Unicode math symbols and LaTeX notation. Type whichever is easier:

| LaTeX | Unicode | Description |
|-------|---------|-------------|
| `\alpha` | `a` | Greek letters |
| `\beta` | `b` | |
| `\pi` | `p` | |
| `\sum` | `` | Summation |
| `\int` | `` | Integral |
| `\infty` | `` | Infinity |
| `^2` | `` | Superscripts |
| `_1` | `` | Subscripts |
| `\dagger` | `` | Hermitian conjugate |
| `\leq` | `` | Less or equal |
| `\RR` | `` | Real numbers |

In the REPL, press Tab after typing LaTeX to convert it to Unicode.

## Language Reference

### Variables

```
let x = 5
let beta = 1.0
let mu = U/2
```

### Functions

```
let f(x) = x^2 + 2*x + 1
let g(x, y) = x^2 + y^2
compute f(5)  # 36
```

### Arithmetic

```
3 + 4 * 2       # 11
2^10            # 1024 (or 2 for Unicode)
sqrt(2)         # 1.414...
exp(1)          # 2.718...
log(e)          # 1.0
sin(pi/2)       # 1.0
```

### Summation

```
# ASCII syntax
sum(n, 1, 100, n)           # 5050
sum(k, 1, 10, k^2)          # 385

# Unicode syntax (equivalent)
sum_{n=1}^{100} n           # 5050
```

### Integration

```
# Definite integral
integrate(sin(x), x, 0, pi)     # 2.0
integrate(x^2, x, 0, 1)         # 0.333...

# Unicode syntax
_0^ sin(x) dx              # 2.0
```

### Linear Algebra

```
let A = matrix([[1, 2], [3, 4]])
compute det(A)              # -2.0
compute trace(A)            # 5.0
compute norm(array(3, 4))   # 5.0
compute inv(A)              # inverse
compute eig(A)              # eigenvalues
```

### Quantum Notation

```
# Hermitian conjugate
A^dagger                    # or A

# Commutator
comm(A, B)                  # [A, B] = AB - BA

# Anticommutator
anticomm(A, B)              # {A, B} = AB + BA

# Trace
Tr(rho * H)

# Tensor product
kron(A, B)                  # A x B
```

### Operators (Quantum Field Theory)

```
operator c[i, sigma] : fermion
operator a[k] : boson
operator S[i] : spin
```

## JAX Backend

Use `-j` flag or `compile_to_jax()` for:

- GPU acceleration
- Automatic differentiation
- JIT compilation

```python
from physlang import compile_to_jax

code = compile_to_jax("""
let f(x) = x^3 + 2*x^2 + x
compute grad(f, 2.0)
""")
# Computes df/dx at x=2.0 using JAX autodiff
```

## Built-in Functions

### Math Functions
`sin`, `cos`, `tan`, `exp`, `log`, `log10`, `sqrt`, `abs`
`sinh`, `cosh`, `tanh`, `arcsin`, `arccos`, `arctan`
`floor`, `ceil`, `round`, `min`, `max`
`factorial`, `gamma`

### Linear Algebra
`det`, `trace`, `norm`, `inv`, `eig`, `eigvals`
`matrix_power`, `kron`, `outer`, `inner`, `cross`

### Array Operations
`array`, `matrix`, `zeros`, `ones`, `eye`, `diag`

### Calculus
`sum(i, start, end, expr)` - Summation
`prod(i, start, end, expr)` - Product
`integrate(expr, var, lower, upper)` - Integration
`grad(f, x)` - Gradient (JAX only)
`hessian(f)` - Hessian matrix (JAX only)

## Examples

### Gauss Sum

```
compute sum(n, 1, 100, n)  # = 100*101/2 = 5050
```

### Basel Problem

```
let s = sum(n, 1, 10000, 1/n^2)
compute s  # approximates pi^2/6
```

### Gaussian Integral

```
compute integrate(exp(-x^2), x, -10, 10)  # approximates sqrt(pi)
```

### Matrix Operations

```
let A = matrix([[1, 2], [3, 4]])
let B = matrix([[5, 6], [7, 8]])
compute A @ B               # matrix multiplication
compute det(A @ B)          # determinant of product
```

### Gradient Descent (JAX)

```
let f(x) = (x - 3)^2
let x = 0.0
let lr = 0.1
# x = x - lr * grad(f, x)  # update step
```

## File Extension

PhysLang files use `.phi` extension:

```bash
physlang program.phi
```

## Why PhysLang?

Every physics paper has equations. Implementing them in code introduces bugs:

- `mu = 0` instead of `mu = U/2`
- Wrong index ordering in tensor products
- Missing signs in commutators
- Incorrect Metropolis-Hastings ratios

PhysLang eliminates translation errors by letting you write the math directly.

## Links

- **PyPI**: [https://pypi.org/project/physlang/](https://pypi.org/project/physlang/)
- **GitHub**: [https://github.com/dmjdxb/PhysLang](https://github.com/dmjdxb/PhysLang)

## Contributing

Contributions welcome. See CONTRIBUTING.md.

## License

Apache License 2.0
