# quansys
**Automated HFSS workflows for quantum circuit design and analysis**
[](https://hutorihunzu.github.io/quansys)
[](https://python.org)
[](LICENSE)
**quansys** is a Python package that automates HFSS electromagnetic simulations for quantum circuit analysis. It provides structured workflows for parameter sweeps, quantum parameter extraction via Energy Participation Ratio (EPR) analysis, and cluster-based execution.
## Features
- **Structured Workflows**: Automated prepare → build → simulate → aggregate pipeline
- **Parameter Sweeps**: Grid and custom parameter sweeps with caching and resumption
- **Quantum Analysis**: EPR-based quantum parameter extraction (χ matrix, dressed frequencies)
- **CLI Interface**: Command-line tools for simulation management and cluster execution
- **Result Processing**: Automatic JSON/CSV output generation for downstream analysis
- **Extensible**: Modular design supporting custom simulation types and builders
## Documentation
Complete documentation is available at: **[hutorihunzu.github.io/quansys](https://hutorihunzu.github.io/quansys)**
## Quick Start
### Installation
Install from PyPI:
```bash
pip install quansys
```
Or install from source:
```bash
git clone https://github.com/hutorihunzu/quansys.git
cd quansys
pip install -e .
```
### Basic Usage
1. **Create a simulation configuration** (`config.yaml`):
```yaml
pyaedt_file_parameters:
file_path: "my_design.aedt"
non_graphical: true
builder:
type: 'design_variable_builder'
design_name: "HfssDesign1"
builder_sweep:
- type: 'DictSweep'
parameters:
resonator_length: ["10mm", "12mm", "14mm"]
simulations:
eigenmode:
type: 'eigenmode'
design_name: "HfssDesign1"
setup_name: "Setup1"
```
2. **Run the simulation**:
```bash
quansys run config.yaml
```
3. **Or use Python directly**:
```python
from quansys.workflow import WorkflowConfig, execute_workflow
config = WorkflowConfig.from_yaml("config.yaml")
execute_workflow(config)
```
## Simulation Types
### Eigenmode Analysis
Extract resonant frequencies and quality factors from electromagnetic eigenmodes:
```python
from quansys.simulation import EigenmodeAnalysis
simulation = EigenmodeAnalysis(
design_name="HfssDesign1",
setup_name="Setup1",
cores=8
)
```
### Quantum EPR Analysis
Compute quantum circuit parameters using Energy Participation Ratio analysis:
```python
from quansys.simulation import QuantumEPR, ConfigJunction
simulation = QuantumEPR(
design_name="HfssDesign1",
setup_name="Setup1",
modes_to_labels={0: "resonator", 1: "transmon"},
junctions_infos=[ConfigJunction(line_name='my_jj_line', inductance_variable_name='lj')]
)
```
> **Note**: Quantum EPR analysis is based on the energy-participation-ratio method from:
> ["Energy-participation quantization of Josephson circuits"](https://doi.org/10.1038/s41534-021-00461-8)
## Cluster Support
**quansys** is designed for high-performance computing environments and is currently optimized for **IBM LSF** cluster systems. The CLI provides tools for:
- Job preparation and submission
- Resource allocation management
- Distributed execution across cluster nodes
- Result aggregation from multiple jobs
> **Cluster Requirement**: This package is specifically tailored for IBM LSF clusters. Support for other cluster systems (SLURM, PBS, etc.) may be added in future releases.
## Development
### Dependencies
- **HFSS/PyAEDT**: Electromagnetic simulation engine
- **QutIP**: Quantum parameter calculations
- **Typer**: CLI interface
- **Pydantic**: Configuration validation
- **Pandas/NumPy**: Data processing
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes with appropriate tests
4. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- **Quantum EPR Analysis**: Based on the energy-participation-ratio method developed in the pyEPR package. See: ["Energy-participation quantization of Josephson circuits"](https://doi.org/10.1038/s41534-021-00461-8)
- **HFSS Integration**: Built on top of [PyAEDT](https://github.com/ansys/pyaedt) for ANSYS Electronics Desktop automation
Raw data
{
"_id": null,
"home_page": null,
"name": "quansys",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "ansys, automation, circuits, electromagnetic, epr, hfss, quantum, simulation, superconducting",
"author": null,
"author_email": "HutoriHunzu <uri.goldblatt@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/3a/a7/e94b20535555fb60f926ebc8a78c8fe89bcbcfa3a3f9af7626715ea5234e/quansys-3.0.0.tar.gz",
"platform": null,
"description": "# quansys\n\n**Automated HFSS workflows for quantum circuit design and analysis**\n\n[](https://hutorihunzu.github.io/quansys)\n[](https://python.org)\n[](LICENSE)\n\n**quansys** is a Python package that automates HFSS electromagnetic simulations for quantum circuit analysis. It provides structured workflows for parameter sweeps, quantum parameter extraction via Energy Participation Ratio (EPR) analysis, and cluster-based execution.\n\n## Features\n\n- **Structured Workflows**: Automated prepare \u2192 build \u2192 simulate \u2192 aggregate pipeline\n- **Parameter Sweeps**: Grid and custom parameter sweeps with caching and resumption\n- **Quantum Analysis**: EPR-based quantum parameter extraction (\u03c7 matrix, dressed frequencies)\n- **CLI Interface**: Command-line tools for simulation management and cluster execution\n- **Result Processing**: Automatic JSON/CSV output generation for downstream analysis\n- **Extensible**: Modular design supporting custom simulation types and builders\n\n## Documentation\n\nComplete documentation is available at: **[hutorihunzu.github.io/quansys](https://hutorihunzu.github.io/quansys)**\n\n## Quick Start\n\n### Installation\n\nInstall from PyPI:\n\n```bash\npip install quansys\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/hutorihunzu/quansys.git\ncd quansys\npip install -e .\n```\n\n### Basic Usage\n\n1. **Create a simulation configuration** (`config.yaml`):\n\n```yaml\npyaedt_file_parameters:\n file_path: \"my_design.aedt\"\n non_graphical: true\n\nbuilder:\n type: 'design_variable_builder'\n design_name: \"HfssDesign1\"\n\nbuilder_sweep:\n - type: 'DictSweep'\n parameters:\n resonator_length: [\"10mm\", \"12mm\", \"14mm\"]\n\nsimulations:\n eigenmode:\n type: 'eigenmode'\n design_name: \"HfssDesign1\"\n setup_name: \"Setup1\"\n```\n\n2. **Run the simulation**:\n\n```bash\nquansys run config.yaml\n```\n\n3. **Or use Python directly**:\n\n```python\nfrom quansys.workflow import WorkflowConfig, execute_workflow\n\nconfig = WorkflowConfig.from_yaml(\"config.yaml\")\nexecute_workflow(config)\n```\n\n## Simulation Types\n\n### Eigenmode Analysis\nExtract resonant frequencies and quality factors from electromagnetic eigenmodes:\n\n```python\nfrom quansys.simulation import EigenmodeAnalysis\n\nsimulation = EigenmodeAnalysis(\n design_name=\"HfssDesign1\",\n setup_name=\"Setup1\",\n cores=8\n)\n```\n\n### Quantum EPR Analysis\nCompute quantum circuit parameters using Energy Participation Ratio analysis:\n\n```python\nfrom quansys.simulation import QuantumEPR, ConfigJunction\n\nsimulation = QuantumEPR(\n design_name=\"HfssDesign1\",\n setup_name=\"Setup1\",\n modes_to_labels={0: \"resonator\", 1: \"transmon\"},\n junctions_infos=[ConfigJunction(line_name='my_jj_line', inductance_variable_name='lj')]\n)\n```\n\n> **Note**: Quantum EPR analysis is based on the energy-participation-ratio method from: \n> [\"Energy-participation quantization of Josephson circuits\"](https://doi.org/10.1038/s41534-021-00461-8)\n\n## Cluster Support\n\n**quansys** is designed for high-performance computing environments and is currently optimized for **IBM LSF** cluster systems. The CLI provides tools for:\n\n- Job preparation and submission\n- Resource allocation management \n- Distributed execution across cluster nodes\n- Result aggregation from multiple jobs\n\n> **Cluster Requirement**: This package is specifically tailored for IBM LSF clusters. Support for other cluster systems (SLURM, PBS, etc.) may be added in future releases.\n\n## Development\n\n### Dependencies\n\n- **HFSS/PyAEDT**: Electromagnetic simulation engine\n- **QutIP**: Quantum parameter calculations\n- **Typer**: CLI interface\n- **Pydantic**: Configuration validation\n- **Pandas/NumPy**: Data processing\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with appropriate tests\n4. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- **Quantum EPR Analysis**: Based on the energy-participation-ratio method developed in the pyEPR package. See: [\"Energy-participation quantization of Josephson circuits\"](https://doi.org/10.1038/s41534-021-00461-8)\n- **HFSS Integration**: Built on top of [PyAEDT](https://github.com/ansys/pyaedt) for ANSYS Electronics Desktop automation",
"bugtrack_url": null,
"license": null,
"summary": "Automated HFSS workflows for quantum circuit design and analysis",
"version": "3.0.0",
"project_urls": {
"Documentation": "https://hutorihunzu.github.io/quansys",
"Homepage": "https://github.com/hutorihunzu/quansys",
"Issues": "https://github.com/hutorihunzu/quansys/issues",
"Repository": "https://github.com/hutorihunzu/quansys"
},
"split_keywords": [
"ansys",
" automation",
" circuits",
" electromagnetic",
" epr",
" hfss",
" quantum",
" simulation",
" superconducting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "858d1b28d8360c02abd900c8e1cd69b553ea9d28fda95b2199df1ef0ef6538f6",
"md5": "eaedb4312d5a94719f2f61ebf0e2b7f4",
"sha256": "1419e7a0dbde6efc10400aa70e1c4cd6bbe4b33890064713dfeb37feeb06dbd7"
},
"downloads": -1,
"filename": "quansys-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eaedb4312d5a94719f2f61ebf0e2b7f4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 203515,
"upload_time": "2025-08-07T09:52:54",
"upload_time_iso_8601": "2025-08-07T09:52:54.777881Z",
"url": "https://files.pythonhosted.org/packages/85/8d/1b28d8360c02abd900c8e1cd69b553ea9d28fda95b2199df1ef0ef6538f6/quansys-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3aa7e94b20535555fb60f926ebc8a78c8fe89bcbcfa3a3f9af7626715ea5234e",
"md5": "8005aa57f33d09423ad0bb2129dcb8db",
"sha256": "635ff17f7d3b1959250a6f3b626324c44cc7fc07a0d756d7e45bec4319ebf965"
},
"downloads": -1,
"filename": "quansys-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8005aa57f33d09423ad0bb2129dcb8db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 624653,
"upload_time": "2025-08-07T09:52:56",
"upload_time_iso_8601": "2025-08-07T09:52:56.951353Z",
"url": "https://files.pythonhosted.org/packages/3a/a7/e94b20535555fb60f926ebc8a78c8fe89bcbcfa3a3f9af7626715ea5234e/quansys-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 09:52:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hutorihunzu",
"github_project": "quansys",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "quansys"
}
JSON
