{"id":50458030,"url":"https://github.com/jacotay7/aobasis","last_synced_at":"2026-06-01T03:08:15.301Z","repository":{"id":325341808,"uuid":"1100236071","full_name":"jacotay7/aobasis","owner":"jacotay7","description":"A library to compute optical bases for a given set of points in 2D space. Main application is intended for adaptive optics, with support for Zernike, KL, Zonal, and Hadamard bases. ","archived":false,"fork":false,"pushed_at":"2026-03-27T02:06:05.000Z","size":5056,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-03T03:51:53.232Z","etag":null,"topics":["adaptive-optics","karhunen-loeve","optics","zernike"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jacotay7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-20T02:43:33.000Z","updated_at":"2026-05-02T07:20:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jacotay7/aobasis","commit_stats":null,"previous_names":["jacotay7/aobasis"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/jacotay7/aobasis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacotay7%2Faobasis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacotay7%2Faobasis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacotay7%2Faobasis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacotay7%2Faobasis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacotay7","download_url":"https://codeload.github.com/jacotay7/aobasis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacotay7%2Faobasis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33757796,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adaptive-optics","karhunen-loeve","optics","zernike"],"created_at":"2026-06-01T03:08:10.909Z","updated_at":"2026-06-01T03:08:15.293Z","avatar_url":"https://github.com/jacotay7.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AO Basis (aobasis)\n\nA Python package for generating various modal basis sets for Adaptive Optics (AO) systems. This tool allows you to easily create, visualize, and save basis sets for any deformable mirror geometry.\n\n## Features\n\n- **Karhunen-Loève (KL) Modes**: Optimized for atmospheric turbulence (Von Kármán spectrum).\n  - Optional GPU acceleration available for large systems (requires CuPy).\n- **Zernike Polynomials**: Standard optical aberration modes (Noll indexing).\n- **Fourier Modes**: Sinusoidal basis sets.\n- **Zonal Basis**: Single actuator pokes (Identity).\n- **Zonal Fast Basis**: Distance-constrained grouped actuator pokes for faster calibration sweeps.\n- **Hadamard Basis**: Orthogonal binary patterns for calibration.\n- **Flexible Geometry**: Works with arbitrary actuator positions (defaulting to circular grids).\n- **Piston Removal**: Option to exclude piston/DC modes from generation.\n- **Visualization**: Built-in plotting tools for quick inspection.\n- **Serialization**: Save and load basis sets to/from `.npz` files.\n\n## Installation\n\n### Prerequisites\n- Python 3.8 or higher\n- (Optional) For GPU-accelerated KL generation: CUDA-compatible GPU and CuPy\n\n### Install from Source\nClone the repository and install using pip:\n\n```bash\ngit clone https://github.com/jacotay7/aobasis.git\ncd aobasis\npip install .\n```\n\nFor development (editable install with test dependencies):\n```bash\npip install -e \".[dev]\"\n```\n\n### GPU Acceleration (Optional)\nTo enable GPU acceleration for KL basis generation, you need to install CuPy and ensure you have a CUDA-compatible GPU.\n\n#### Requirements\n- NVIDIA GPU with CUDA support\n- CUDA Toolkit (version 11.x or 12.x)\n\n#### Installation via Conda (Recommended)\nThis method automatically handles CUDA dependencies:\n\n```bash\n# Create a new conda environment (optional but recommended)\nconda create -n aobasis python=3.12\nconda activate aobasis\n\n# Install CuPy from conda-forge (auto-detects CUDA version)\nconda install -c conda-forge cupy\n\n# Install CUDA toolkit if not already present\nconda install -c nvidia cuda-toolkit\n```\n\n#### Installation via Pip\nIf you prefer pip and already have CUDA installed on your system:\n\n```bash\n# For CUDA 12.x\npip install cupy-cuda12x\n\n# For CUDA 11.x\npip install cupy-cuda11x\n```\n\n#### Verify Installation\nTest that CuPy is working correctly:\n\n```python\nimport cupy as cp\nprint(f\"CuPy version: {cp.__version__}\")\nprint(f\"CUDA available: {cp.cuda.is_available()}\")\n\n# Simple test\na = cp.array([1, 2, 3])\nb = cp.array([4, 5, 6])\nprint(f\"Sum: {cp.asnumpy(a + b)}\")  # Should print [5, 7, 9]\n```\n\nIf you encounter any issues, consult the [CuPy installation guide](https://docs.cupy.dev/en/stable/install.html).\n\n## Quick Start\n\nHere is a simple example of generating and plotting KL modes for a 10-meter telescope:\n\n```python\nfrom aobasis import KLBasisGenerator, make_circular_actuator_grid\n\n# 1. Define the actuator geometry\npositions = make_circular_actuator_grid(telescope_diameter=10.0, grid_size=20)\n\n# 2. Initialize the generator (use_gpu=True for GPU acceleration if available)\nkl_gen = KLBasisGenerator(positions, fried_parameter=0.16, outer_scale=30.0, use_gpu=False)\n\n# 3. Generate modes (excluding piston)\nmodes = kl_gen.generate(n_modes=50, ignore_piston=True)\n\n# 4. Plot the first 6 modes\nkl_gen.plot(count=6, title_prefix=\"KL Mode\")\n\n# 5. Save to disk\nkl_gen.save(\"my_kl_basis.npz\")\n```\n\n## Zonal Fast Basis\n\n`ZonalFastBasisGenerator` groups actuators into binary poke patterns such that no two actuators in the same mode are closer than a user-defined distance `D`. This is useful when you want a compact calibration basis that reduces the number of measurements compared with pure zonal pokes. For square-grid actuator layouts it uses a modulo lattice grouping directly, and for exotic layouts it falls back to a greedy graph-coloring approach.\n\n```python\nimport numpy as np\n\nfrom aobasis import ZonalFastBasisGenerator, make_circular_actuator_grid, make_concentric_actuator_grid\n\n# Example 1: grid-like actuator positions clipped by a circular pupil.\npositions = make_circular_actuator_grid(telescope_diameter=10.0, grid_size=20)\ngrid_gen = ZonalFastBasisGenerator(positions, min_distance=0.8)\ngrid_modes = grid_gen.generate()\nprint(\"Grid layout:\", grid_modes.shape)\ngrid_gen.plot(count=min(12, grid_modes.shape[1]), title_prefix=\"Zonal Fast Grid\")\n\n# Example 2: non-grid actuator positions.\nexotic_positions = make_concentric_actuator_grid(telescope_diameter=10.0, n_rings=5)\nexotic_positions = exotic_positions + 0.03 * np.sin(exotic_positions)\nexotic_gen = ZonalFastBasisGenerator(exotic_positions, min_distance=1.0)\nexotic_modes = exotic_gen.generate()\nprint(\"Exotic layout:\", exotic_modes.shape)\nexotic_gen.plot(count=min(12, exotic_modes.shape[1]), title_prefix=\"Zonal Fast Exotic\")\n```\n\nThe returned matrix still has the standard `(n_actuators, n_modes)` layout, but each column is now a sparse binary pattern rather than a single-actuator poke. Every actuator appears in exactly one column of the full basis.\n\n## Performance\n\nGeneration times for 100 modes benchmarked on the following system:\n- **CPU**: AMD Ryzen 9 9950X3D (16-core, 32-thread)\n- **GPU**: NVIDIA GeForce RTX 5090 (32 GB)\n- **OS**: Linux (Ubuntu)\n\n| Basis | 16x16 Grid (~170 acts) | 32x32 Grid (~740 acts) | 64x64 Grid (~3100 acts) |\n|-------|------------------------|------------------------|-------------------------|\n| **KL (CPU)** | 0.010s | 0.170s | 3.008s |\n| **KL (GPU)** | 0.005s | 0.019s | 0.202s |\n| **Zernike** | 0.001s | 0.002s | 0.005s |\n| **Fourier** | \u003c0.001s | 0.001s | 0.003s |\n| **Zonal** | \u003c0.001s | \u003c0.001s | 0.003s |\n| **Zonal Fast** | depends on spacing threshold | depends on spacing threshold | depends on spacing threshold |\n| **Hadamard** | \u003c0.001s | 0.001s | 0.031s |\n\n*Note: KL basis generation is computationally intensive ($O(N^3)$) due to the dense covariance matrix diagonalization. GPU acceleration provides significant speedup (8-15x) for larger grids.*\n\n## Tutorials\n\nWe provide Jupyter notebooks to help you get started.\n\n1.  **Getting Started**: `tutorials/getting_started.ipynb` covers all supported basis types, including zonal fast grouped pokes.\n\nTo run the tutorials:\n```bash\n# Install Jupyter if you haven't already\npip install jupyter\n\n# Launch the notebook server\njupyter notebook tutorials/getting_started.ipynb\n```\n\n## Development \u0026 Testing\n\nThis project uses `pytest` for testing. To run the test suite:\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1.  Fork the repository.\n2.  Create your feature branch (`git checkout -b feature/AmazingFeature`).\n3.  Commit your changes (`git commit -m 'Add some AmazingFeature'`).\n4.  Push to the branch (`git push origin feature/AmazingFeature`).\n5.  Open a Pull Request.\n\n## Issues\n\nIf you encounter any bugs or have feature requests, please file an issue on the [GitHub Issues](https://github.com/jacotay7/aobasis/issues) page.\n\n## Contact\n\nFor questions or support, please contact:\n\n**User Name**  \nEmail: jacobataylor7@gmail.com\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacotay7%2Faobasis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacotay7%2Faobasis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacotay7%2Faobasis/lists"}