Metadata-Version: 2.4
Name: impulsox_mna
Version: 0.1
Summary: An advanced package for the simulation of analog electronic circuits using Modified Nodal Analysis
Project-URL: Homepage, https://github.com/kvdijken/impulsox-mna
Author-email: kvdijken <sla_nippers_0x@icloud.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.14
Requires-Dist: numpy
Provides-Extra: examples
Requires-Dist: labellines; extra == 'examples'
Requires-Dist: matplotlib; extra == 'examples'
Requires-Dist: quantiphy; extra == 'examples'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown


# impulsox-mna

![Status](https://img.shields.io/badge/status-experimental-orange)
![Focus](https://img.shields.io/badge/focus-advanced%20features-blue)
![Architecture](https://img.shields.io/badge/architecture-independent-success)
![Contributions](https://img.shields.io/badge/contributions-welcome-brightgreen)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

**impulsox-mna** is an advanced Python package for circuit simulation based on **Modified Nodal Analysis (MNA)**. It is designed as a platform for more demanding use cases and ongoing development of advanced simulation techniques.

The package is installed as `impulsox-mna` and imported as:

```python
import impulsox as imp
```

---

## ✨ Features

### Currently implemented

* Modified Nodal Analysis (MNA) engine

* Unified framework for:

  * DC operating point analysis
  * AC small-signal analysis
  * Transient simulation

* Solver improvements over `impulso-mna`:

  * Reuse of previous solution vectors across iterations
  * Option to re-stamp only nonlinear components (avoiding unnecessary re-stamping of linear components)

These features primarily target **performance and convergence efficiency** in iterative solving.

---

### Planned / future features

The project is intended as a foundation for more advanced capabilities, which may include:

* Advanced semiconductor device models (e.g. detailed BJT/MOSFET models)
* Enhanced nonlinear convergence strategies
* Sparse matrix and high-performance solver backends
* RF and high-frequency analysis tools
* Noise analysis
* More sophisticated simulation workflows

These features are **not yet implemented** but represent the intended direction of the project.

---

## 📦 Installation

```bash
pip install impulsox-mna
```

For development:

```bash
git clone https://github.com/<your-username>/impulsox-mna.git
cd impulsox-mna
pip install -e .
```

---

## 🚀 Quick Example

```python
import impulsox as imp

ckt = imp.Circuit()

ckt.add(imp.Resistor("R1", n1=1, n2=0, value=1e3))
ckt.add(imp.VoltageSource("V1", n_plus=1, n_minus=0, value=5.0))

result = ckt.solve_transient(t_stop=1e-3, dt=1e-6)

print(result.node_voltages)
```

---

## 📊 Example Simulations

The repository includes examples demonstrating more advanced simulation workflows and solver behavior.

### 1. Nonlinear Device Characterization

* Demonstrates improved iteration efficiency using solution reuse

---

### 2. Transistor-Level Circuit Analysis

* Multi-device circuits benefiting from selective re-stamping

---

### 3. Time-Domain Signal Processing Circuits

* Transient simulations with iterative solver improvements

---

### 4. High-Fidelity Transient Response

* Focus on stability and efficiency rather than new physical models

---

## 🧠 Design Philosophy

* **Performance-oriented**: Focus on improving solver efficiency
* **Experimental**: A space for developing and testing advanced ideas
* **Flexible**: Designed for extension and modification
* **Self-contained**: No dependency on `impulso-mna`

While it shares conceptual similarities with `impulso-mna`, this package is implemented independently and is free to evolve in more complex directions.

---

## 🔗 Relationship to impulso-mna

```text
impulso-mna   → minimal, stable, educational core
impulsox-mna  → experimental, advanced, independently evolving implementation
```

* No dependency between the packages
* Similar conceptual structure and API philosophy
* Different design goals and complexity levels

Users can choose the package that best fits their needs:

* Use **`impulso-mna`** for simplicity and clarity
* Use **`impulsox-mna`** for experimentation and advanced solver behavior

---
Good idea — a comparison table makes the distinction immediately clear.

Here’s a section you can drop right after **“Relationship to impulso-mna”**:

---

## 📊 impulso-mna vs impulsox-mna

| Aspect                  | impulso-mna                           | impulsox-mna                                            |
| ----------------------- | ------------------------------------- | ------------------------------------------------------- |
| **Purpose**             | Minimal, stable MNA core              | Experimental, advanced development platform             |
| **Complexity**          | Low                                   | Moderate → High                                         |
| **Dependencies**        | Minimal                               | Minimal (but more open to change)                       |
| **Architecture**        | Simple, explicit                      | Flexible, evolving                                      |
| **Solver behavior**     | Standard iteration                    | Improved iteration (solution reuse, selective stamping) |
| **Performance focus**   | Secondary                             | Primary focus                                           |
| **Advanced features**   | Not included                          | In development / planned                                |
| **Stability**           | High (intentionally stable)           | Evolving                                                |
| **Use case**            | Learning, prototyping, small circuits | Research, experimentation, larger/complex circuits      |
| **Dependency relation** | —                                     | Independent (no dependency on impulso-mna)              |


---

## 🧩 Component Model

Components follow the same general MNA principles:

* Matrix stamping for linear elements
* Augmented variables for sources and dynamic components
* Linearization of nonlinear devices

Current focus is on **solver-level improvements**, with future work potentially expanding into more advanced component models.

---

## 🔧 Development Workflow

```bash
pip install -e .[dev]
```

Typical structure:

```
.
├── impulsox/
├── examples/
├── tests/
└── pyproject.toml
```

---

## 📈 Performance Notes

* Improved efficiency through reduced re-stamping
* Faster convergence via solution reuse
* Designed as a testbed for further performance enhancements

---

## 🤝 Contributing

Contributions are highly encouraged.

This project is explicitly intended as a **collaborative space for advanced features**, and many planned capabilities are not yet implemented.

Areas where contributions would be especially valuable:

* Advanced device modeling
* Numerical methods and convergence strategies
* Sparse matrix and solver optimizations
* RF / frequency-domain extensions
* Noise analysis
* Benchmarking and validation

If you are interested in circuit simulation, numerical methods, or MNA-based solvers, your contributions can have a direct impact on the direction of this project.

---

## 📄 License

MIT License (or your chosen license)

---

## 🏁 Roadmap

**impulsox-mna** is expected to evolve actively.

Near-term focus:

* Further solver performance improvements
* Refinement of current iteration strategies

Long-term direction:

* Expansion into advanced modeling and simulation techniques
* Development of high-performance solver infrastructure

## 📦 Requirements

### ▶️ Core (runtime)

The core of **impulsox-mna** is intentionally lightweight and depends only on a small set of packages:

* `numpy` — numerical computations and matrix operations

These are the only dependencies required to **use the simulator itself**.

---

### 📊 Optional (examples & visualization)

The following packages are used for running examples and visualizing results:

* `matplotlib` — plotting simulation results
* `quantiphy` — formatted physical quantities

`matplotlib` brings in several supporting dependencies (e.g. `cycler`, `kiwisolver`, `pillow`, etc.).

---

### 🧪 Development & testing

For development, testing, and contributing:

* `pytest` — test framework
* `pluggy`, `iniconfig`, `Pygments` — pytest dependencies

---

### 🛠 Build system

* `setuptools`
* `wheel`

---

### 🔗 Development note on impulso-mna

During development, you may encounter setups that include:

```
-e git+https://github.com/kvdijken/impulso-mna.git@<commit>#egg=impulso
```

This is **only for development and comparison purposes**.

* **impulsox-mna does not depend on impulso-mna**
* Both packages are fully independent implementations

---

## ⚙️ Installation

### Minimal installation

```bash
pip install impulsox-mna
```

---

### Development environment

To reproduce the full development setup:

```bash
pip install -r requirements.txt
```

---

## 📝 Notes

* Runtime dependencies are intentionally minimal
* Additional packages are only required for examples, testing, and development
* Future versions may formalize this split via optional dependency groups (e.g. `extras_require`)
