diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 00000000..33e88920 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,55 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + - release/v2.0 + paths: + - 'book/**' + - 'book.toml' + - '.github/workflows/deploy-docs.yml' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup mdBook + uses: peaceiris/actions-mdbook@v2 + with: + mdbook-version: 'latest' + + - name: Setup Pages + uses: actions/configure-pages@v4 + + - name: Build documentation + run: mdbook build + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./book/docs + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 0628b05a..0e340d41 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,6 @@ __pycache__/ # UV virtual environment .venv/ uv.lock + +# mdbook +book/book/ diff --git a/book.toml b/book.toml new file mode 100644 index 00000000..dec5bfef --- /dev/null +++ b/book.toml @@ -0,0 +1,45 @@ +[book] +title = "StarPerf Documentation" +authors = ["StarPerf Team"] +description = "A comprehensive platform for simulating and analyzing mega-constellation satellite network performance" +language = "en" +multilingual = false +src = "book/src" + +[build] +build-dir = "book/docs" + +[output.html] +default-theme = "dark" +preferred-dark-theme = "navy" +git-repository-url = "https://github.com/SpaceNetLab/StarPerf_Simulator" +git-repository-icon = "fa-github" +edit-url-template = "https://github.com/SpaceNetLab/StarPerf_Simulator/edit/main/book/src/{path}" +site-url = "/StarPerf_Simulator/" +cname = "" + +[output.html.fold] +enable = true +level = 0 + +[output.html.search] +enable = true +limit-results = 30 +teaser-word-count = 30 +use-boolean-and = true +boost-title = 2 +boost-hierarchy = 1 +boost-paragraph = 1 +expand = true +heading-split-level = 3 + +[output.html.playground] +editable = false +copyable = true +copy-js = true +line-numbers = true + +[preprocessor.katex] + +[output.html.print] +enable = true diff --git a/book/src/README.md b/book/src/README.md new file mode 100644 index 00000000..7256ee34 --- /dev/null +++ b/book/src/README.md @@ -0,0 +1,51 @@ +# StarPerf: Emerging Mega-Constellations LEO Network Performance Simulator + +Welcome to the StarPerf documentation! This comprehensive guide will help you understand and use StarPerf, a powerful platform for simulating and analyzing the network performance of mega-constellation satellite networks such as Starlink and OneWeb. + +## What is StarPerf? + +"Newspace" mega-constellations are gaining tremendous popularity, with the promising potential to provide high-capacity and low-latency communication globally. StarPerf enables constellation manufacturers and content providers to estimate and understand the achievable performance under a variety of constellation options. + +## Key Features + +StarPerf integrates four key techniques: + +1. **Performance Simulation for Mega-Constellation** + - Captures the impact of inherent high mobility in satellite networks and profiles area-to-area attainable network performance + +2. **Constellation Scaling** + - Synthesizes various topological options by scaling space resources (e.g., number of satellites, link availability and capacity) + +3. **Constellation Visualization** + - Leverages Cesium to render mainstream LEO constellations in a highly interactive and realistic 3D environment + +4. **Security Simulation** + - Based on attack modeling and numerical simulation, including traffic plugins and communication energy consumption plugins + +## StarPerf 2.0 + +StarPerf 2.0 represents a major upgrade from version 1.0: + +- **Pure Python Implementation**: No longer depends on third-party orbit analysis tools (STK, GMAT) +- **Framework + Plugin Architecture**: Highly extensible and modular design +- **Enhanced Functionality**: Richer features and improved usability +- **Python 3.10+ Required**: Modern Python environment + +## QuickStart + +- [Getting Started](./getting-started/overview.md) - Learn the basics and get up and running +- [Installation Guide](./getting-started/installation.md) - Set up your environment +- [Architecture Overview](./user-guide/architecture.md) - Understand the system design +- [API Reference](./api-reference/introduction.md) - Detailed interface documentation +- [Examples](./examples/overview.md) - Practical usage examples + +## Contact + +If you have any questions about StarPerf, please don't hesitate to contact us: + +- Email: zeqilai AT tsinghua.edu.cn +- Email: houyn24 AT mails.tsinghua.edu.cn +- Email: ZhifengHan AT mail.com +- Email: lijh19 AT mails.tsinghua.edu.cn + +Happy benchmarking your constellation! πŸ›°οΈ diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md new file mode 100644 index 00000000..e0346a43 --- /dev/null +++ b/book/src/SUMMARY.md @@ -0,0 +1,123 @@ +# Summary + +[Introduction](./README.md) + +# Getting Started + +- [Overview](./getting-started/overview.md) +- [Installation](./getting-started/installation.md) +- [Quick Start](./getting-started/quick-start.md) + +# User Guide + +- [Introduction](./user-guide/introduction.md) +- [Environment & Dependencies](./user-guide/environment.md) +- [Architecture](./user-guide/architecture.md) +- [Configuration Module](./user-guide/configuration.md) + - [H5 File Format](./user-guide/config/h5-format.md) + - [TLE Constellation](./user-guide/config/tle-constellation.md) + - [XML Constellation](./user-guide/config/xml-constellation.md) + - [Ground Stations](./user-guide/config/ground-stations.md) + - [POPs](./user-guide/config/pops.md) +- [Data Storage Module](./user-guide/data-storage.md) +- [Auxiliary Scripts](./user-guide/auxiliary-scripts.md) + +# Core Modules + +- [Kernel Module Overview](./core-modules/overview.md) + +## Constellation Generation + +- [Overview](./core-modules/constellation-generation/overview.md) +- [XML-based Generation](./core-modules/constellation-generation/xml-based.md) + - [constellation_configuration.py](./core-modules/constellation-generation/xml-constellation-config.md) + - [orbit_configuration.py](./core-modules/constellation-generation/xml-orbit-config.md) + - [Case Study](./core-modules/constellation-generation/xml-case-study.md) +- [TLE-based Generation](./core-modules/constellation-generation/tle-based.md) + - [download_TLE_data.py](./core-modules/constellation-generation/tle-download.md) + - [satellite_to_shell_mapping.py](./core-modules/constellation-generation/tle-shell-mapping.md) + - [satellite_to_orbit_mapping.py](./core-modules/constellation-generation/tle-orbit-mapping.md) + - [get_satellite_position.py](./core-modules/constellation-generation/tle-position.md) + - [constellation_configuration.py](./core-modules/constellation-generation/tle-constellation-config.md) + - [Case Study](./core-modules/constellation-generation/tle-case-study.md) +- [Duration-based Generation](./core-modules/constellation-generation/duration-based.md) + +## Standalone Modules + +- [Satellite Visibility Time](./core-modules/standalone-modules/satellite-visibility.md) + +## Beam Placement + +- [Overview](./core-modules/beam-placement/overview.md) +- [Plugin Specification](./core-modules/beam-placement/plugins.md) +- [Framework](./core-modules/beam-placement/framework.md) +- [Case Study](./core-modules/beam-placement/case-study.md) + +## Connectivity + +- [Overview](./core-modules/connectivity/overview.md) +- [Plugin Specification](./core-modules/connectivity/plugins.md) +- [Framework](./core-modules/connectivity/framework.md) +- [Case Study](./core-modules/connectivity/case-study.md) + +## Performance Evaluation + +- [Overview](./core-modules/evaluation/overview.md) +- [With ISL](./core-modules/evaluation/with-isl.md) + - [Bandwidth](./core-modules/evaluation/isl-bandwidth.md) + - [Betweenness](./core-modules/evaluation/isl-betweenness.md) + - [Coverage](./core-modules/evaluation/isl-coverage.md) + - [Delay](./core-modules/evaluation/isl-delay.md) +- [Without ISL (Bent-pipe)](./core-modules/evaluation/without-isl.md) + - [Bandwidth](./core-modules/evaluation/bentpipe-bandwidth.md) + - [Coverage](./core-modules/evaluation/bentpipe-coverage.md) + - [Delay](./core-modules/evaluation/bentpipe-delay.md) + +## Entity Classes + +- [Overview](./core-modules/entity/overview.md) + +## Routing + +- [Overview](./core-modules/routing/overview.md) +- [Plugin Specification](./core-modules/routing/plugins.md) +- [Framework](./core-modules/routing/framework.md) + +## High Survivability + +- [Overview](./core-modules/survivability/overview.md) +- [Plugin Specification](./core-modules/survivability/plugins.md) +- [Framework](./core-modules/survivability/framework.md) + +# Visualization + +- [Constellation Visualization](./visualization/constellation.md) +- [Setup Instructions](./visualization/setup.md) + +# Examples + +- [Overview](./examples/overview.md) +- [XML Constellation Example](./examples/xml-constellation.md) +- [TLE Constellation Example](./examples/tle-constellation.md) +- [Beam Placement Example](./examples/beam-placement.md) +- [Connectivity Example](./examples/connectivity.md) +- [Performance Evaluation Example](./examples/evaluation.md) + +# API Reference + +- [Introduction](./api-reference/introduction.md) +- [Plugin Interfaces](./api-reference/plugin-interfaces.md) +- [Entity Classes](./api-reference/entities.md) +- [Utility Functions](./api-reference/utilities.md) + +# Contributing + +- [How to Contribute](./contributing/how-to-contribute.md) +- [Writing Plugins](./contributing/writing-plugins.md) +- [Code Style Guide](./contributing/code-style.md) + +# About + +- [License](./about/license.md) +- [Contact](./about/contact.md) +- [Contributors](./about/contributors.md) diff --git a/book/src/about/contact.md b/book/src/about/contact.md new file mode 100644 index 00000000..34e97eff --- /dev/null +++ b/book/src/about/contact.md @@ -0,0 +1,232 @@ +# Contact + +We welcome questions, feedback, and collaboration opportunities related to StarPerf! + +## Development Team + +### Primary Contacts + +For general questions about StarPerf: + +- **Houyn** - houyn24@mails.tsinghua.edu.cn +- **Zhifeng Han** - ZhifengHan.mail@gmail.com +- **Zeqi Lai** - zeqilai@tsinghua.edu.cn +- **Lijh** - lijh19@mails.tsinghua.edu.cn + +### Response Time + +We aim to respond to inquiries within: +- **Bug reports**: 1-2 business days +- **Feature requests**: 3-5 business days +- **General questions**: 1 week + +## Getting Help + +### Before Contacting + +Please check these resources first: + +1. **Documentation** + - Read through relevant sections of this documentation + - Check the [API Reference](../api-reference/introduction.md) + - Review [Examples](../examples/overview.md) + +2. **GitHub Issues** + - Search [existing issues](https://github.com/SpaceNetLab/StarPerf_Simulator/issues) + - Check [closed issues](https://github.com/SpaceNetLab/StarPerf_Simulator/issues?q=is%3Aissue+is%3Aclosed) for solved problems + +3. **Documentation Search** + - Use the search function (top of page) to find relevant topics + +### What to Include + +When contacting us, please provide: + +1. **Clear Description** + - What you're trying to accomplish + - What you've tried so far + - What's not working + +2. **Environment Information** + ```bash + # Include output of: + python --version + uv --version + # Your operating system + ``` + +3. **Code Examples** + ```python + # Minimal reproducible example + # Include relevant code snippets + ``` + +4. **Error Messages** + ``` + # Full error traceback + # Any warning messages + ``` + +## Reporting Issues + +### Bug Reports + +Found a bug? Please report it via [GitHub Issues](https://github.com/SpaceNetLab/StarPerf_Simulator/issues/new): + +**Include:** +- Detailed description of the bug +- Steps to reproduce +- Expected vs. actual behavior +- Environment information +- Screenshots (if applicable) + +**Template:** +```markdown +## Description +Brief description of the issue + +## Steps to Reproduce +1. Step one +2. Step two +3. ... + +## Expected Behavior +What should happen + +## Actual Behavior +What actually happens + +## Environment +- OS: [e.g., macOS 13.0] +- Python version: [e.g., 3.10.5] +- StarPerf version: [e.g., 2.0] + +## Additional Context +Any other relevant information +``` + +### Feature Requests + +Have an idea for a new feature? We'd love to hear it! + +**Submit via:** +- GitHub Issues with `[Feature Request]` label +- Email to the development team + +**Include:** +- Use case description +- Why this feature would be valuable +- Proposed implementation (if you have ideas) +- Examples from other tools (if applicable) + +## Contributing + +Want to contribute code, documentation, or constellation designs? + +1. **Read Contributing Guidelines** + - See [How to Contribute](../contributing/how-to-contribute.md) + - Review [Writing Plugins](../contributing/writing-plugins.md) + +2. **Fork and Clone** + ```bash + git clone https://github.com/YOUR_USERNAME/StarPerf_Simulator.git + cd StarPerf_Simulator + ``` + +3. **Create Branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +4. **Submit Pull Request** + - Include clear description + - Reference related issues + - Add tests if applicable + +## Collaboration Opportunities + +### Research Collaboration + +We're open to research collaborations on: +- Mega-constellation network analysis +- Satellite network performance +- Space-terrestrial network integration +- Security analysis of satellite networks + +**Contact:** houyn24@mails.tsinghua.edu.cn + +### Industry Partnerships + +Interested in using StarPerf for commercial applications or partnerships? + +**Contact:** ZhifengHan.mail@gmail.com + +### Educational Use + +Using StarPerf for teaching or academic purposes? +- We can provide additional resources +- Help with course material development +- Offer guest lectures (subject to availability) + +**Contact:** zeqilai@tsinghua.edu.cn + +## Community + +### Stay Updated + +- **GitHub**: [Watch repository](https://github.com/SpaceNetLab/StarPerf_Simulator) for updates +- **Stars**: Give us a star if you find StarPerf useful! +- **Releases**: Check [releases page](https://github.com/SpaceNetLab/StarPerf_Simulator/releases) for new versions + +### Discussion Forums + +For community discussions: +- Open a [GitHub Discussion](https://github.com/SpaceNetLab/StarPerf_Simulator/discussions) +- Ask questions and share experiences +- Help other users + +## Social Media + +Stay connected: +- GitHub: [@SpaceNetLab](https://github.com/SpaceNetLab) + +## Office Hours + +Currently, we don't have scheduled office hours, but we're responsive to emails and GitHub issues. + +## Mailing List + +Want to stay informed about StarPerf updates? +- Star the repository on GitHub +- Watch for releases and announcements + +## Code of Conduct + +We are committed to providing a welcoming and inclusive environment for all contributors and users. Please: + +- Be respectful and constructive +- Focus on what is best for the community +- Show empathy towards others +- Accept constructive criticism gracefully + +## Privacy + +When contacting us: +- We respect your privacy +- Emails are only used for StarPerf-related communication +- We don't share contact information with third parties + +## Acknowledgments + +Thank you to everyone who has contributed to StarPerf through: +- Code contributions +- Bug reports +- Feature suggestions +- Documentation improvements +- Spreading the word + +Your support makes StarPerf better for everyone! + +--- + +[← Back to Contributors](./contributors.md) | [View License β†’](./license.md) diff --git a/book/src/about/contributors.md b/book/src/about/contributors.md new file mode 100644 index 00000000..e75d2894 --- /dev/null +++ b/book/src/about/contributors.md @@ -0,0 +1,284 @@ +# Contributors + +StarPerf is developed and maintained by a dedicated team of researchers and engineers committed to advancing satellite network simulation capabilities. + +## Core Team + +### Research Lead +The project is led by researchers from Tsinghua University's Department of Computer Science and Technology. + +### Development Team + +The core development team includes: + +- **Houyn** - Core architecture and framework development + - Email: houyn24@mails.tsinghua.edu.cn + +- **Zhifeng Han** - Algorithm design and performance optimization + - Email: ZhifengHan.mail@gmail.com + +- **Zeqi Lai** - Visualization and data analysis + - Email: zeqilai@tsinghua.edu.cn + +- **Lijh** - Testing and documentation + - Email: lijh19@mails.tsinghua.edu.cn + +## Institutional Support + +### Tsinghua University +StarPerf is developed at Tsinghua University, one of China's leading research institutions. + +**Department**: Computer Science and Technology + +**Lab**: SpaceNetLab - Focusing on space-terrestrial integrated networks research + +## Contribution Types + +### Code Contributors +Developers who have contributed to the codebase: +- Core framework implementation +- Plugin development +- Bug fixes and optimizations +- Test coverage improvements + +### Documentation Contributors +Those who have helped improve documentation: +- User guide authors +- API documentation writers +- Tutorial creators +- Translation support + +### Research Contributors +Researchers who have used StarPerf in their work: +- Published papers citing StarPerf +- Validation and testing +- Feature requirements and feedback +- Use case studies + +### Community Contributors +Community members who have helped: +- Bug reports +- Feature requests +- Answering questions +- Promoting StarPerf + +## How to Become a Contributor + +We welcome contributions from everyone! Here's how you can help: + +### 1. Code Contributions + +**What we need:** +- New plugins (routing algorithms, connectivity modes, etc.) +- Performance improvements +- Bug fixes +- Test coverage +- New constellation configurations + +**How to contribute:** +```bash +# Fork the repository +git clone https://github.com/YOUR_USERNAME/StarPerf_Simulator.git + +# Create a feature branch +git checkout -b feature/my-contribution + +# Make your changes +# ... code ... + +# Commit and push +git add . +git commit -m "Add: brief description" +git push origin feature/my-contribution + +# Open a Pull Request on GitHub +``` + +See [How to Contribute](../contributing/how-to-contribute.md) for details. + +### 2. Documentation Contributions + +**What we need:** +- Tutorial improvements +- Translation to other languages +- Code examples +- FAQ entries +- Video tutorials + +**How to help:** +- Documentation is in `book/src/` +- Follow the existing style +- Include code examples where applicable +- Test all examples + +### 3. Testing and Feedback + +**What helps:** +- Report bugs with detailed reproduction steps +- Test new features +- Provide performance benchmarks +- Share use cases + +### 4. Constellation Designs + +**What we'd love:** +- New constellation configurations +- Real TLE data for additional constellations +- Validation data +- Performance benchmarks + +## Recognition + +### Contributors Wall + +We maintain a list of all contributors who have made significant contributions: + +- **Pull Request Authors**: Listed in GitHub +- **Issue Reporters**: Acknowledged in issue discussions +- **Major Contributors**: Featured here and in publications + +### Citation Credits + +If your contribution leads to a research publication, we ensure proper citation and acknowledgment: + +```bibtex +@inproceedings{starperf, + title={StarPerf: A Network Performance Simulator}, + author={Core Team and Contributors}, + ... +} +``` + +## Contribution Guidelines + +### Code Quality + +- Follow Python PEP 8 style guide +- Include docstrings for all functions +- Add type hints where applicable +- Write tests for new features + +### Documentation Standards + +- Use clear, concise language +- Include code examples +- Test all examples +- Update relevant sections + +### Communication + +- Be respectful and constructive +- Provide context in issues and PRs +- Respond to feedback promptly +- Help review others' contributions + +## Special Thanks + +### Research Community + +Thank you to researchers who have: +- Published papers using StarPerf +- Provided valuable feedback +- Shared validation data +- Cited our work + +### Open Source Community + +We're grateful to: +- Python community for excellent libraries +- Open source projects we depend on +- GitHub for hosting and tools +- Users who report issues and suggest features + +### Funding Support + +StarPerf development has been supported by: +- Research grants +- University funding +- Collaborative projects + +## Join Us + +Want to be part of the StarPerf community? + +1. **Star the Repository** + - Show your support on [GitHub](https://github.com/SpaceNetLab/StarPerf_Simulator) + +2. **Fork and Contribute** + - Start with small contributions + - Graduate to larger features + +3. **Engage in Discussions** + - Answer questions + - Share experiences + - Provide feedback + +4. **Spread the Word** + - Share with colleagues + - Write blog posts + - Present at conferences + +## Contributor Stats + +### By the Numbers + +- **Total Contributors**: Growing community +- **Commits**: Thousands of improvements +- **Issues Resolved**: Hundreds of bug fixes +- **Pull Requests**: Community contributions + +### Top Contributors + +Contributors are recognized based on: +- Number of commits +- Quality of contributions +- Community engagement +- Long-term involvement + +## Future Goals + +We're always looking for help with: + +### Short-term +- Expanding documentation with more examples +- Adding test coverage +- Improving performance +- Bug fixes + +### Long-term +- Support for more constellation types +- Integration with other tools +- Advanced visualization features +- Machine learning capabilities + +## Become a Maintainer + +Exceptional contributors may be invited to join as maintainers with: +- Direct commit access +- PR review responsibilities +- Roadmap input +- Community leadership roles + +**Criteria:** +- Consistent quality contributions +- Good communication skills +- Understanding of project goals +- Community engagement + +## Contact for Contribution Questions + +Have questions about contributing? + +- **General**: Open a GitHub Discussion +- **Specific**: Email any core team member +- **Complex**: Schedule a video call + +See [Contact](./contact.md) for details. + +--- + +**Thank you to all our contributors!** Your efforts make StarPerf a better platform for everyone. πŸš€ + +--- + +[← Back to License](./license.md) | [Contact Us β†’](./contact.md) diff --git a/book/src/about/license.md b/book/src/about/license.md new file mode 100644 index 00000000..4d469924 --- /dev/null +++ b/book/src/about/license.md @@ -0,0 +1,114 @@ +# License + +StarPerf 1.0 and StarPerf 2.0 are open source projects licensed under the BSD-2-Clause License. + +## BSD-2-Clause License + +Copyright (c) StarPerf Team. All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +## What This Means + +The BSD-2-Clause License is a permissive open source license that allows you to: + +### βœ… You Can + +- **Use** the software for any purpose, including commercial applications +- **Modify** the source code to suit your needs +- **Distribute** the original or modified versions +- **Incorporate** StarPerf into proprietary software +- **Use privately** without any obligation to share modifications + +### ⚠️ You Must + +- **Include the license** and copyright notice in any redistribution +- **Include the disclaimer** in binary distributions +- **Give credit** to the original authors + +### ❌ You Cannot + +- **Hold liable** the authors or copyright holders for any damages +- **Use trademarks** without permission +- **Remove** or alter license notices + +## Third-Party Dependencies + +StarPerf uses several third-party Python libraries, each with their own licenses: + +| Library | License | Use Case | +|---------|---------|----------| +| h3 | Apache-2.0 | Geospatial indexing | +| h5py | BSD-3-Clause | HDF5 file handling | +| numpy | BSD-3-Clause | Numerical computing | +| pandas | BSD-3-Clause | Data manipulation | +| skyfield | MIT | Satellite position calculation | +| sgp4 | MIT | Orbital propagation | +| poliastro | MIT | Astrodynamics | +| astropy | BSD-3-Clause | Astronomy computations | +| networkx | BSD-3-Clause | Graph algorithms | +| requests | Apache-2.0 | HTTP library | +| jenkspy | MIT | Natural breaks algorithm | +| pyecharts | MIT | Visualization | +| openpyxl | MIT | Excel file processing | +| global_land_mask | MIT | Land/ocean detection | +| importlib-metadata | Apache-2.0 | Package metadata | + +All dependencies are compatible with the BSD-2-Clause License and can be used together in the same project. + +## Citations + +If you use StarPerf in your research, please cite: + +```bibtex +@inproceedings{starperf, + title={StarPerf: A Network Performance Simulator for Emerging Mega-Constellations}, + author={Your Team}, + booktitle={Conference Name}, + year={2024} +} +``` + +## Related Publications + +StarPerf has been used in the following research: + +1. **Time-varying Bottleneck Links in LEO Satellite Networks** + - Published in NDSS 2025 + - [Link to paper](https://www.ndss-symposium.org/ndss-paper/time-varying-bottleneck-links-in-leo-satellite-networks-identification-exploits-and-countermeasures/) + +2. **Energy Drain Attack in Satellite Internet Constellations** + - Published in IWQoS 2023 + - [Link to paper](https://ieeexplore.ieee.org/document/10188709) + +## Acknowledgments + +StarPerf is developed and maintained by researchers from: +- Tsinghua University +- [Other institutions] + +We thank all contributors and the open source community for their valuable input and support. + +## Contact for Licensing Questions + +For questions about licensing, commercial use, or other legal matters, please contact: + +- Email: houyn24@mails.tsinghua.edu.cn +- Email: ZhifengHan.mail@gmail.com + +## License History + +- **Version 2.0** (2023-Present): BSD-2-Clause License +- **Version 1.0** (2019-2023): BSD-2-Clause License + +The license has remained consistent across versions, maintaining the project's commitment to open source principles. + +--- + +[← Back to About](./contact.md) | [View on GitHub β†’](https://github.com/SpaceNetLab/StarPerf_Simulator) diff --git a/book/src/api-reference/entities.md b/book/src/api-reference/entities.md new file mode 100644 index 00000000..27c9d783 --- /dev/null +++ b/book/src/api-reference/entities.md @@ -0,0 +1 @@ +# Entity Classes diff --git a/book/src/api-reference/introduction.md b/book/src/api-reference/introduction.md new file mode 100644 index 00000000..ba5312dd --- /dev/null +++ b/book/src/api-reference/introduction.md @@ -0,0 +1,326 @@ +# API Reference Introduction + +This section provides detailed documentation of StarPerf's programming interfaces, helping you understand and extend the platform. + +## Overview + +StarPerf 2.0 follows a **"Framework + Plugin"** architecture, where: + +- **Framework**: Provides core functionality and standardized APIs +- **Plugins**: Implement specific features using the framework's APIs + +This design enables high extensibility while maintaining consistency across the platform. + +## API Categories + +### 1. Entity Classes + +Core data structures representing constellation components: +- `Constellation` - Complete satellite network +- `Shell` - Orbital shell within a constellation +- `Orbit` - Circular path containing satellites +- `Satellite` - Individual spacecraft +- `GroundStation` - Ground infrastructure +- `User` - Communication endpoint +- `POP` - Point of presence + +[Learn more β†’](./entities.md) + +### 2. Plugin Interfaces + +Standardized interfaces for extending functionality: +- **Beam Placement Plugins** - Satellite beam scheduling algorithms +- **Connectivity Plugins** - Inter-satellite link establishment +- **Routing Plugins** - Path selection strategies +- **Survivability Plugins** - Damage and failure modeling + +[Learn more β†’](./plugin-interfaces.md) + +### 3. Utility Functions + +Helper functions for common operations: +- Position calculations +- Distance computations +- Coverage analysis +- Data I/O operations + +[Learn more β†’](./utilities.md) + +## API Design Principles + +### 1. Consistency + +All plugins follow the same patterns: +```python +# Every plugin has: +# 1. Standard location in src/[constellation_type]/[module]/[category]_plugin/ +# 2. Entry function with same name as file +# 3. Standardized parameter list +# 4. Well-defined return values +``` + +### 2. Type Safety + +Functions use clear type hints: +```python +def constellation_configuration( + dT: int, + constellation_name: str +) -> Constellation: + """ + Generate constellation from XML configuration. + + Args: + dT: Timestamp interval in seconds + constellation_name: Name of constellation + + Returns: + Constellation object + """ + pass +``` + +### 3. Documentation + +Every function includes: +- Purpose description +- Parameter specifications (name, type, unit, meaning) +- Return value description +- Usage examples + +### 4. Extensibility + +Clear interfaces enable custom implementations: +```python +# Write your own plugin following the interface: +def my_custom_routing(constellation: Constellation, dT: int) -> None: + """ + Custom routing strategy. + + Must follow routing plugin interface specifications. + """ + # Your implementation here + pass +``` + +## Common API Patterns + +### Pattern 1: Manager-Based Plugin Execution + +Most plugins use a manager for execution: + +```python +# 1. Import manager +from src.XML_constellation.constellation_connectivity import connectivity_mode_plugin_manager + +# 2. Instantiate manager +manager = connectivity_mode_plugin_manager.connectivity_mode_plugin_manager() + +# 3. Set plugin +manager.set_connection_mode("positive_Grid") + +# 4. Execute +manager.execute_connection_policy( + constellation=constellation, + dT=dT +) +``` + +### Pattern 2: Direct Function Call + +Some modules provide direct functions: + +```python +# Import function directly +from src.standalone_module import satellite_visibility_time + +# Call with parameters +visibility_time = satellite_visibility_time.satellite_visibility_time( + ΞΈ=25, # Elevation angle + h=550 # Orbital altitude +) +``` + +### Pattern 3: Configuration-Based Initialization + +Constellation generation uses configuration: + +```python +from src.constellation_generation.by_XML import constellation_configuration + +# Configuration read from XML file +constellation = constellation_configuration.constellation_configuration( + dT=5730, + constellation_name="Starlink" # Reads config/XML_constellation/Starlink.xml +) +``` + +## Parameter Units + +StarPerf uses consistent units across all APIs: + +| Quantity | Unit | Example | +|----------|------|---------| +| Time | seconds | `dT = 1000` | +| Distance | kilometers | `altitude = 550` | +| Angle | degrees | `inclination = 53.0` | +| Bandwidth | Gbps | `isl_capacity = 5.0` | +| Frequency | GHz | `uplink = 2.1` | +| Latitude | degrees | `lat = 47.6` | +| Longitude | degrees | `lon = -122.3` | + +## Data Storage Conventions + +### HDF5 File Structure + +StarPerf uses HDF5 for efficient data storage: + +```python +import h5py + +# Standard structure: +# constellation.h5 +# β”œβ”€β”€ position/ +# β”‚ β”œβ”€β”€ shell1/ +# β”‚ β”‚ β”œβ”€β”€ timeslot1 (dataset) +# β”‚ β”‚ └── timeslot2 (dataset) +# β”‚ └── shell2/ +# └── delay/ +# β”œβ”€β”€ shell1/ +# └── shell2/ +``` + +### File Paths + +```python +# XML constellation data +data_path = f"data/XML_constellation/{constellation_name}.h5" + +# TLE constellation data +data_path = f"data/TLE_constellation/{constellation_name}.h5" + +# Configuration files +config_path = f"config/XML_constellation/{constellation_name}.xml" +config_path = f"config/TLE_constellation/{constellation_name}/tle.h5" +``` + +## Error Handling + +StarPerf uses standard Python exceptions: + +```python +try: + constellation = constellation_configuration.constellation_configuration( + dT=5730, + constellation_name="NonExistent" + ) +except FileNotFoundError as e: + print(f"Configuration file not found: {e}") +except ValueError as e: + print(f"Invalid parameter: {e}") +``` + +## Best Practices + +### 1. Use Type Hints + +```python +from typing import List, Dict, Optional + +def analyze_coverage( + constellation: Constellation, + resolution: int = 2 +) -> List[float]: + """Return coverage values for each timeslot.""" + pass +``` + +### 2. Validate Parameters + +```python +def set_resolution(resolution: int) -> None: + """Set H3 resolution (must be 0-4).""" + if not 0 <= resolution <= 4: + raise ValueError(f"Resolution must be 0-4, got {resolution}") + # ... +``` + +### 3. Document Units + +```python +def calculate_delay( + distance_km: float, + speed_of_light_kmps: float = 299792.458 +) -> float: + """ + Calculate propagation delay. + + Args: + distance_km: Distance in kilometers + speed_of_light_kmps: Speed of light in km/s + + Returns: + Delay in seconds + """ + return distance_km / speed_of_light_kmps +``` + +### 4. Use Descriptive Names + +```python +# Good +satellite_altitude_km = 550 +minimum_elevation_angle_deg = 25 + +# Avoid +h = 550 +e = 25 +``` + +## Quick Reference + +### Constellation Generation + +```python +# XML-based +from src.constellation_generation.by_XML import constellation_configuration +constellation = constellation_configuration.constellation_configuration(dT, constellation_name) + +# TLE-based +from src.constellation_generation.by_TLE import constellation_configuration +constellation = constellation_configuration.constellation_configuration(dT, constellation_name) +``` + +### Connectivity + +```python +from src.XML_constellation.constellation_connectivity import connectivity_mode_plugin_manager +manager = connectivity_mode_plugin_manager.connectivity_mode_plugin_manager() +manager.execute_connection_policy(constellation, dT) +``` + +### Evaluation + +```python +from src.XML_constellation.constellation_evaluation import evaluation + +# Coverage +coverage = evaluation.coverage(constellation_name, dT, sh, tile_size, minimum_elevation) + +# Delay +delay = evaluation.delay(constellation_name, source, target, dT, sh) + +# Bandwidth +bandwidth = evaluation.bandwidth(constellation_name, source, target, sh, Ξ», isl_capacity, dT) +``` + +## Next Steps + +Explore detailed API documentation: +- [Entity Classes](./entities.md) - Core data structures +- [Plugin Interfaces](./plugin-interfaces.md) - Extension points +- [Utility Functions](./utilities.md) - Helper functions + +Or see APIs in action: +- [Examples](../examples/overview.md) - Practical usage examples +- [Core Modules](../core-modules/overview.md) - Module documentation diff --git a/book/src/api-reference/plugin-interfaces.md b/book/src/api-reference/plugin-interfaces.md new file mode 100644 index 00000000..fb1c2fa9 --- /dev/null +++ b/book/src/api-reference/plugin-interfaces.md @@ -0,0 +1 @@ +# Plugin Interfaces diff --git a/book/src/api-reference/utilities.md b/book/src/api-reference/utilities.md new file mode 100644 index 00000000..782b445c --- /dev/null +++ b/book/src/api-reference/utilities.md @@ -0,0 +1 @@ +# Utility Functions diff --git a/book/src/contributing/code-style.md b/book/src/contributing/code-style.md new file mode 100644 index 00000000..7fe26c97 --- /dev/null +++ b/book/src/contributing/code-style.md @@ -0,0 +1 @@ +# Code Style Guide diff --git a/book/src/contributing/how-to-contribute.md b/book/src/contributing/how-to-contribute.md new file mode 100644 index 00000000..df35e73d --- /dev/null +++ b/book/src/contributing/how-to-contribute.md @@ -0,0 +1,438 @@ +# How to Contribute + +We welcome and appreciate contributions to StarPerf! This guide will help you get started. + +## Ways to Contribute + +### 1. Bug Reports πŸ› + +Found a bug? Help us improve by reporting it! + +**Where to report:** +- [GitHub Issues](https://github.com/SpaceNetLab/StarPerf_Simulator/issues) + +**What to include:** +- Clear, descriptive title +- Steps to reproduce +- Expected vs actual behavior +- Environment details (OS, Python version, etc.) +- Error messages and stack traces +- Screenshots if applicable + +**Template:** +```markdown +**Description** +Clear description of the bug + +**To Reproduce** +1. Step one +2. Step two +3. See error + +**Expected Behavior** +What should happen + +**Actual Behavior** +What actually happens + +**Environment** +- OS: macOS 13.0 +- Python: 3.10.5 +- StarPerf: 2.0 + +**Additional Context** +Any other relevant information +``` + +### 2. Feature Requests πŸ’‘ + +Have an idea for a new feature? + +**Submit via:** +- GitHub Issues with `[Feature Request]` label + +**Include:** +- Clear description of the feature +- Use case and motivation +- Proposed implementation (if you have ideas) +- Alternative solutions considered + +### 3. Code Contributions πŸ’» + +Ready to write code? Great! + +**Process:** +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Write/update tests +5. Update documentation +6. Submit a pull request + +See [Development Workflow](#development-workflow) below for details. + +### 4. Documentation πŸ“š + +Help make StarPerf easier to use! + +**Areas:** +- User guides and tutorials +- API documentation +- Code examples +- README improvements +- Typo fixes + +### 5. Constellation Designs πŸ›°οΈ + +Contribute new constellation configurations! + +**What we need:** +- New XML constellation configs +- Real TLE data for additional constellations +- Validation data and benchmarks +- Ground station and POP configurations + +### 6. Test Cases πŸ§ͺ + +Improve code quality with tests! + +**Types:** +- Unit tests for individual functions +- Integration tests for workflows +- Performance benchmarks +- Edge case scenarios + +## Development Workflow + +### Step 1: Fork and Clone + +```bash +# Fork on GitHub, then clone your fork +git clone https://github.com/YOUR_USERNAME/StarPerf_Simulator.git +cd StarPerf_Simulator + +# Add upstream remote +git remote add upstream https://github.com/SpaceNetLab/StarPerf_Simulator.git +``` + +### Step 2: Set Up Environment + +```bash +# Install uv if not already installed +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Install dependencies +uv sync + +# Verify installation +uv run python StarPerf.py +``` + +### Step 3: Create Branch + +```bash +# Update main branch +git checkout main +git pull upstream main + +# Create feature branch with descriptive name +git checkout -b feature/add-new-routing-plugin +# or +git checkout -b fix/satellite-position-bug +# or +git checkout -b docs/improve-api-reference +``` + +**Branch naming conventions:** +- `feature/description` - New features +- `fix/description` - Bug fixes +- `docs/description` - Documentation +- `refactor/description` - Code refactoring +- `test/description` - Test additions + +### Step 4: Make Changes + +Write your code following our [Code Style Guide](./code-style.md). + +**Guidelines:** +- Write clear, self-documenting code +- Add comments for complex logic +- Include docstrings for all functions +- Follow existing patterns in the codebase + +**Example:** +```python +def calculate_satellite_coverage( + satellite: Satellite, + h3_resolution: int = 2, + minimum_elevation: float = 25.0 +) -> List[str]: + """ + Calculate H3 cells covered by satellite. + + Args: + satellite: Satellite object to analyze + h3_resolution: H3 grid resolution (0-4) + minimum_elevation: Minimum elevation angle in degrees + + Returns: + List of H3 cell IDs covered by satellite + + Raises: + ValueError: If resolution is not in range 0-4 + """ + if not 0 <= h3_resolution <= 4: + raise ValueError(f"Resolution must be 0-4, got {h3_resolution}") + + # Implementation + covered_cells = [] + # ... + return covered_cells +``` + +### Step 5: Test Your Changes + +```bash +# Run existing tests (if available) +uv run python -m pytest tests/ + +# Test your specific changes +uv run python samples/your_test_case.py + +# Manual testing +uv run python StarPerf.py +``` + +### Step 6: Commit Changes + +Write clear, descriptive commit messages: + +```bash +# Stage your changes +git add . + +# Commit with descriptive message +git commit -m "Add: New routing plugin for shortest path with QoS + +- Implement QoS-aware shortest path algorithm +- Add tests for QoS routing +- Update documentation with usage example +- Fixes #123" +``` + +**Commit message format:** +``` +Type: Brief description (50 chars or less) + +More detailed explanation if needed. Wrap at 72 characters. + +- Bullet points for multiple changes +- Reference issues: Fixes #123, Relates to #456 +``` + +**Commit types:** +- `Add:` New features +- `Fix:` Bug fixes +- `Update:` Updates to existing features +- `Remove:` Removal of code +- `Refactor:` Code refactoring +- `Docs:` Documentation changes +- `Test:` Test additions/changes + +### Step 7: Push and Create PR + +```bash +# Push to your fork +git push origin feature/add-new-routing-plugin +``` + +Then on GitHub: +1. Navigate to your fork +2. Click "Compare & pull request" +3. Fill out the PR template +4. Submit the pull request + +**PR Title Format:** +``` +[Type] Brief description + +Examples: +[Feature] Add QoS-aware routing plugin +[Fix] Correct satellite position calculation +[Docs] Improve installation guide +``` + +**PR Description Template:** +```markdown +## Description +Brief description of changes + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Documentation +- [ ] Refactoring + +## Changes Made +- Change 1 +- Change 2 +- Change 3 + +## Testing +- [ ] Tested locally +- [ ] Added new tests +- [ ] All existing tests pass + +## Related Issues +Fixes #123 +Relates to #456 + +## Screenshots (if applicable) +[Add screenshots] + +## Checklist +- [ ] Code follows style guidelines +- [ ] Self-review completed +- [ ] Comments added for complex code +- [ ] Documentation updated +- [ ] No new warnings generated +``` + +## Review Process + +### What Happens Next + +1. **Automated Checks** + - CI/CD pipeline runs (if configured) + - Code quality checks + - Test execution + +2. **Code Review** + - Maintainer reviews your code + - May request changes + - Discussion and iteration + +3. **Approval and Merge** + - Once approved, PR is merged + - Your contribution is part of StarPerf! + +### Review Timeline + +- **Initial review**: Within 1 week +- **Follow-up**: 2-3 business days +- **Approval**: When all feedback is addressed + +### Responding to Feedback + +```bash +# Make requested changes +# ... edit files ... + +# Commit changes +git add . +git commit -m "Update: Address review feedback + +- Fix variable naming as suggested +- Add error handling +- Improve documentation" + +# Push updates +git push origin feature/add-new-routing-plugin +``` + +The PR automatically updates with your new commits. + +## Contribution Standards + +### Code Quality + +- βœ… Follow PEP 8 style guide +- βœ… Include type hints +- βœ… Write docstrings +- βœ… Add comments for complex logic +- βœ… Keep functions focused and small +- βœ… Use descriptive variable names + +### Testing + +- βœ… Test your changes thoroughly +- βœ… Add automated tests if possible +- βœ… Verify existing tests still pass +- βœ… Test edge cases + +### Documentation + +- βœ… Update relevant documentation +- βœ… Add docstrings to new functions +- βœ… Include usage examples +- βœ… Update CHANGELOG (if applicable) + +## Communication + +### Be Respectful + +- Use welcoming and inclusive language +- Respect differing viewpoints +- Accept constructive criticism gracefully +- Focus on what's best for the community + +### Be Clear + +- Provide context in issues and PRs +- Explain your reasoning +- Ask questions if something is unclear +- Respond to feedback promptly + +## Getting Help + +Stuck? Need guidance? + +1. **Check Documentation** + - Read relevant sections + - Review examples + - Check API reference + +2. **Search Existing Issues** + - Someone may have asked before + - Check closed issues too + +3. **Ask Questions** + - Open a GitHub Discussion + - Email the development team + - Be specific about your problem + +4. **Join the Community** + - Engage in discussions + - Help others + - Share your experiences + +## Recognition + +Contributors are recognized through: + +- πŸ† GitHub contributors list +- πŸ“ Acknowledgments in documentation +- 🎯 Mentions in release notes +- 🌟 Featured on contributors page + +Significant contributors may be invited to join as maintainers! + +## License + +By contributing, you agree that your contributions will be licensed under the BSD-2-Clause License. See [License](../about/license.md) for details. + +## Questions? + +Have questions about contributing? + +- πŸ“§ Email: houyn24@mails.tsinghua.edu.cn +- πŸ’¬ GitHub Discussions +- πŸ“ Open an issue + +--- + +**Thank you for contributing to StarPerf!** πŸš€ + +--- + +[Next: Writing Plugins β†’](./writing-plugins.md) diff --git a/book/src/contributing/writing-plugins.md b/book/src/contributing/writing-plugins.md new file mode 100644 index 00000000..68228309 --- /dev/null +++ b/book/src/contributing/writing-plugins.md @@ -0,0 +1 @@ +# Writing Plugins diff --git a/book/src/core-modules/beam-placement/case-study.md b/book/src/core-modules/beam-placement/case-study.md new file mode 100644 index 00000000..d4b70890 --- /dev/null +++ b/book/src/core-modules/beam-placement/case-study.md @@ -0,0 +1 @@ +# Case Study diff --git a/book/src/core-modules/beam-placement/framework.md b/book/src/core-modules/beam-placement/framework.md new file mode 100644 index 00000000..2660e90d --- /dev/null +++ b/book/src/core-modules/beam-placement/framework.md @@ -0,0 +1 @@ +# Framework diff --git a/book/src/core-modules/beam-placement/overview.md b/book/src/core-modules/beam-placement/overview.md new file mode 100644 index 00000000..9fcffba2 --- /dev/null +++ b/book/src/core-modules/beam-placement/overview.md @@ -0,0 +1,144 @@ +# Beam Placement + +This part includes two aspects. One is "framework" part: beam placement plug-in manager, another is the "plug-in" part: various beam placement algorithms. + +## Overview + +The beam placement module is responsible for determining how satellite beams are directed to cover areas on Earth's surface. StarPerf 2.0 uses a plugin-based architecture that allows for flexible implementation of different beam placement strategies. + +## Architecture + +The beam placement module consists of: + +1. **Framework**: `beam_placement_plugin_manager.py` - manages all beam placement plugins +2. **Plugins**: Various beam placement algorithms (e.g., `random_placement.py`) + +## Plug-ins + +All plug-ins under this module are beam placement algorithms, and one plug-in represents a beam placement algorithm. We implement the random beam placement algorithm (i.e. `random_placement.py`) by default, and you can write other beam placement algorithm plug-ins by yourself according to the interface specifications. + +### Interface Specifications + +The interface specifications for beam placement plugins are as follows: + +- **Requirement 1**: The storage location of the plug-in is (starting from the root of StarPerf 2.0): `src/TLE_constellation/constellation_beamplacement/beam_placement_plugin/` (for TLE constellation) or `src/XML_constellation/constellation_beamplacement/beam_placement_plugin/` (for XML constellation). + +- **Requirement 2**: Each plug-in is a ".py" file, and all source code for the plug-in must be located in this script file. + +- **Requirement 3**: The launch entry for a plug-in is a function with the same name as the plug-in. + +- **Requirement 4**: The startup function parameter requirements are as follows: + +**Table: beam placement plug-ins startup function parameter list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :---------------------------: | :------------: | :------------: | :---------------------------------------------------------------------------------------------------------------: | +| sh | shell | - | a shell class object, representing a layer of shell in the constellation | +| h3_resolution | int | - | the resolution of cells divided by h3 library, and currently supported resolutions are: 0/1/2/3/4 | +| antenna_count_per_satellite | int | - | the number of antennas each satellite is equipped with | +| dT | int | second | indicates how often the beam is scheduled, and this value must be less than the orbital period of the satellite | +| minimum_elevation | float | degree | the minimum elevation angle at which a satellite can be seen from a point on the ground | + +- **Requirement 5**: The return value of the startup function is all cells covered after executing the beam placement algorithm. + +- **Requirement 6**: If one plug-in needs to save intermediate data or result data, the data should be saved in an h5 format file under "data/". + +## Framework + +This part of the framework consists of 1 py script: `beam_placement_plugin_manager.py`. A beam placement plug-in manager is defined in this script to manage all plug-ins under this module. + +The so-called beam placement plug-in manager actually defines a class named `beam_placement_plugin_manager`. The attributes and methods contained in this class and their functions and meanings are shown in the tables below. + +### Attributes + +**Table: beam placement plug-in manager attributes list** + +| Attribute Name | Attribute Type | Attribute Meaning | +| :------------------------------: | :------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| plugins | dict | a dictionary composed of all plug-ins. The "key" is the plug-in name, which is a string type, and the "value" is the plug-in startup function in the corresponding plug-in, which is a function | +| current_beamplacement_policy | str | plug-in name used by the current beam placement plug-in manager | + +### Methods + +**Table: beam placement plug-in manager methods list** + +| Method Name | Parameter List
(name : type : unit) | Return Values | Method Function | +| :------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| \_\_init\_\_ | - | - | initialize an instance of the beam placement plugin manager | +| set_beamplacement_policy | (plugin_name : str : -) | - | set the value of current_beamplacement_policy to plugin_name | +| execute_beamplacement_policy | (sh : shell : - ,
h3_resolution : int : - , antenna_count_per_satellite : int : - ,
dT : int : second , minimum_elevation : float : degree) | cells covered by the beam, all cells | according to the value of the current_beamplacement_policy attribute, the startup function of the corresponding plug-in is called to execute the beam placement algorithm. | + +## Operating Mechanism + +The operating mechanism of this framework is: + +1. First instantiate a beam placement plug-in manager object. This object contains two attributes: `plugins` and `current_beamplacement_policy`. + - `plugins` is a dictionary type attribute used to store various beam placement plugins + - `current_beamplacement_policy` is a string type used to represent the beam placement plugin used by the current manager + +2. During the instantiation of the manager object, the system automatically reads all beam placement plug-ins and stores them in the `plugins`. The key of `plugins` is the name of the plugin, and the value of `plugins` is the startup function of the plugin. + +3. After reading all plug-ins, the system sets the value of `current_beamplacement_policy` to "random_placement", indicating that the "random_placement" plug-in is used as the default beam placement algorithm. + +4. If you want to execute the beam placement algorithm, you only need to call the `execute_beamplacement_policy` method of the manager object. This method will automatically call the startup function of the plug-in indicated by `current_beamplacement_policy`. + +5. If you need to switch the beam placement plug-in, just call the `set_beamplacement_policy` method and pass in the plug-in name you need as a parameter. + +6. After you write your own beam placement algorithm plug-in according to the interface specifications introduced earlier, you only need to set `current_beamplacement_policy` as your plug-in name, and the system will automatically recognize your plug-in and execute it. + +## Case Study + +Now, we take "random_placement" as an example to explain the operation of the beam placement module. + +### Step 1: Instantiate the Manager + +```python +beamPlacementPluginManager = beam_placement_plugin_manager.beam_placement_plugin_manager() +``` + +### Step 2: Set the Beam Placement Plugin + +```python +beamPlacementPluginManager.set_beamplacement_policy("random_placement") +``` + +**Note**: The beam placement plug-in manager already sets the `current_beamplacement_policy` value to "random_placement" when initialized, so this step can be omitted here. But if you want to use other beam placement plug-ins, this step cannot be omitted. + +### Step 3: Execute the Beam Placement Algorithm + +```python +covered_cells_per_timeslot, Cells = beamPlacementPluginManager.execute_beamplacement_policy( + bent_pipe_constellation.shells[0], + h3_resolution, + antenna_count_per_satellite, + dT, + minimum_elevation +) +``` + +There are two return values in Step 3: +- `covered_cells_per_timeslot` represents the cells covered by the beam +- `Cells` represents all cells (including those covered by the beam and those not covered by the beam) + +### Results + +The code execution results are as follows (part): + +![Beam Random Placement Execution Result](../../images/beam_random_placement_execution_result.png) + +The complete code of the above process can be found at: `samples/TLE_constellation/beam_placement/random_placement.py` and `samples/XML_constellation/beam_placement/random_placement.py`. + +## Creating Custom Beam Placement Algorithms + +To create your own beam placement algorithm: + +1. Create a new Python file in the `beam_placement_plugin/` directory +2. Implement a function with the same name as the file +3. Follow the parameter and return value specifications outlined above +4. The plugin will be automatically discovered and loaded by the manager + +## Navigation + +- [Back to Core Modules Overview](../overview.md) +- [Connectivity Overview](../connectivity/overview.md) +- [Evaluation Overview](../evaluation/overview.md) diff --git a/book/src/core-modules/beam-placement/plugins.md b/book/src/core-modules/beam-placement/plugins.md new file mode 100644 index 00000000..8efd0556 --- /dev/null +++ b/book/src/core-modules/beam-placement/plugins.md @@ -0,0 +1 @@ +# Plugin Specification diff --git a/book/src/core-modules/connectivity/case-study.md b/book/src/core-modules/connectivity/case-study.md new file mode 100644 index 00000000..d4b70890 --- /dev/null +++ b/book/src/core-modules/connectivity/case-study.md @@ -0,0 +1 @@ +# Case Study diff --git a/book/src/core-modules/connectivity/framework.md b/book/src/core-modules/connectivity/framework.md new file mode 100644 index 00000000..2660e90d --- /dev/null +++ b/book/src/core-modules/connectivity/framework.md @@ -0,0 +1 @@ +# Framework diff --git a/book/src/core-modules/connectivity/overview.md b/book/src/core-modules/connectivity/overview.md new file mode 100644 index 00000000..64ee1614 --- /dev/null +++ b/book/src/core-modules/connectivity/overview.md @@ -0,0 +1,151 @@ +# Constellation Connectivity + +This section is also composed of "framework" and "plug-ins". The "framework" part is the "connectivity mode plugin manager". The "plug-ins" part is the connection method between satellites, such as +Grid. + +## Overview + +The connectivity module determines how Inter-Satellite Links (ISLs) are established between satellites in the constellation. Different connectivity patterns affect network topology, routing efficiency, and overall performance. + +## Architecture + +The connectivity module consists of: + +1. **Framework**: `connectivity_mode_plugin_manager.py` - manages all connectivity mode plugins +2. **Plugins**: Various ISL establishment modes (e.g., `positive_Grid.py`, `bent_pipe.py`) + +## Plug-ins + +All plug-ins under this module are ISL establishment modes, and one plug-in represents a mode. We implement the +Grid mode and bent-pipe mode by default, and you can write other ISL establishment mode plug-ins by yourself according to the interface specifications. + +### Interface Specifications + +The interface specifications for connectivity plugins are as follows: + +- **Requirement 1**: The storage location of the plug-in is (starting from the root of StarPerf 2.0): `src/TLE_constellation/constellation_connectivity/connectivity_plugin/` (for TLE constellation) or `src/XML_constellation/constellation_connectivity/connectivity_plugin/` (for XML constellation). + +- **Requirement 2**: Each plug-in is a ".py" file, and all source code for the plug-in must be located in this script file. + +- **Requirement 3**: The launch entry for a plug-in is a function with the same name as the plug-in. + +- **Requirement 4**: The startup function parameter requirements are as follows: + +**Table: ISL establishment mode plug-ins startup function parameter list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :------------: | :------------: | :------------: | :----------------------------------------------------------: | +| constellation | constellation | - | the constellation to establish ISL | +| dT | int | second | indicates how often the beam is scheduled, and this value must be less than the orbital period of the satellite | + +- **Requirement 5**: The startup function has no return value. + +- **Requirement 6**: After establishing the ISL, write the constellation delay matrix into a .h5 file. The Group name is: "delay", and the Dataset name is: "timeslot+\" (such as "timeslot1", "timeslot2"), and the .h5 file storage path: `data/TLE_constellation/` (for TLE constellation) or `data/XML_constellation/` (for XML constellation). + +## Framework + +This part of the framework consists of 1 py script: `connectivity_mode_plugin_manager.py`. A connectivity mode plugin manager is defined in this script to manage all plug-ins under this module. + +The so-called connectivity mode plugin manager actually defines a class named `connectivity_mode_plugin_manager`. The attributes and methods contained in this class and their functions and meanings are shown in the tables below. + +### Attributes + +**Table: connectivity mode plugin manager attributes list** + +| Attribute Name | Attribute Type | Attribute Meaning | +| :---------------------: | :------------: | :----------------------------------------------------------: | +| plugins | dict | a dictionary composed of all plug-ins. The "key" is the plug-in name, which is a string type, and the "value" is the plug-in startup function in the corresponding plug-in, which is a function | +| current_connection_mode | str | plug-in name used by the current connectivity mode plugin manager | + +### Methods + +**Table: connectivity mode plugin manager methods list** + +| Method Name | Parameter List
(name : type : unit) | Return Values | Method Function | +| :-----------------------: | :----------------------------------------------------------: | :-----------: | :----------------------------------------------------------: | +| \_\_init\_\_ | - | - | initialize an instance of the connectivity mode plugin manager | +| set_connection_mode | (plugin_name : str : -) | - | set the value of current_connection_mode to plugin_name | +| execute_connection_policy | (constellation : constellation : - ,
dT : int : second) | - | according to the value of the current_connection_mode attribute, the startup function of the corresponding plug-in is called to execute the ISL establishment. | + +## Operating Mechanism + +The operating mechanism of this framework is: + +1. First instantiate a connectivity mode plugin manager object. This object contains two attributes: `plugins` and `current_connection_mode`. + - `plugins` is a dictionary type attribute used to store various connectivity mode plugins + - `current_connection_mode` is a string type used to represent the connectivity mode plugin used by the current manager + +2. During the instantiation of the manager object, the system automatically reads all connectivity mode plugins and stores them in the `plugins`. The key of `plugins` is the name of the plugin, and the value of `plugins` is the startup function of the plugin. + +3. After reading all plug-ins, the system sets the value of `current_connection_mode` to "positive_Grid", indicating that the "positive_Grid" plug-in is used as the default connectivity mode plugin. + +4. If you want to execute the connectivity mode, you only need to call the `execute_connection_policy` method of the manager object. This method will automatically call the startup function of the plug-in indicated by `current_connection_mode`. + +5. If you need to switch the connectivity mode plug-in, just call the `set_connection_mode` method and pass in the plug-in name you need as a parameter. + +6. After you write your own connectivity mode plug-in according to the interface specifications introduced earlier, you only need to set `current_connection_mode` as your plug-in name, and the system will automatically recognize your plug-in and execute it. + +## Connectivity Modes + +### +Grid Mode + +The +Grid connectivity pattern establishes ISLs in a grid-like pattern, connecting satellites both within the same orbital plane and across adjacent orbital planes. This creates a mesh network topology that enables flexible routing. + +### Bent-pipe Mode + +In bent-pipe mode, satellites act as simple relays between ground stations without ISLs. All traffic must pass through ground stations, simplifying satellite design but limiting coverage and requiring more ground infrastructure. + +## Case Study + +Now, we take "positive_Grid" as an example to explain the operation of the constellation connectivity module. + +### Step 1: Instantiate the Manager + +```python +# initialize the connectivity mode plugin manager +connectionModePluginManager = connectivity_mode_plugin_manager.connectivity_mode_plugin_manager() +``` + +### Step 2: Set the Connectivity Mode Plugin + +```python +connectionModePluginManager.current_connection_mode = "positive_Grid" +``` + +**Note**: The connectivity mode plugin manager already sets the `current_connection_mode` value to "positive_Grid" when initialized, so this step can be omitted here. But if you want to use other connectivity mode plugins, this step cannot be omitted. + +### Step 3: Execute the Connection Policy + +```python +connectionModePluginManager.execute_connection_policy(constellation=bent_pipe_constellation, dT=dT) +``` + +### Results + +After execution, the constellation delay matrix will be written to the appropriate .h5 file, and the ISL topology will be established according to the selected connectivity pattern. + +The complete code of the above process can be found at: `samples/XML_constellation/positive_Grid/*` and `samples/TLE_constellation/positive_Grid/*`. + +## Creating Custom Connectivity Modes + +To create your own connectivity mode: + +1. Create a new Python file in the `connectivity_plugin/` directory +2. Implement a function with the same name as the file +3. Follow the parameter and return value specifications outlined above +4. Ensure the delay matrix is properly written to the .h5 file +5. The plugin will be automatically discovered and loaded by the manager + +## Considerations for Connectivity Design + +When designing or selecting a connectivity mode, consider: + +- **Link Budget**: Can satellites maintain reliable ISLs at the required distances? +- **Pointing Complexity**: How many simultaneous links can each satellite maintain? +- **Handover Frequency**: How often do ISLs need to be reconfigured? +- **Routing Efficiency**: Does the topology support efficient path finding? +- **Fault Tolerance**: Can the network maintain connectivity if satellites fail? + +## Navigation + +- [Back to Core Modules Overview](../overview.md) +- [Previous: Beam Placement](../beam-placement/overview.md) +- [Next: Evaluation Overview](../evaluation/overview.md) diff --git a/book/src/core-modules/connectivity/plugins.md b/book/src/core-modules/connectivity/plugins.md new file mode 100644 index 00000000..8efd0556 --- /dev/null +++ b/book/src/core-modules/connectivity/plugins.md @@ -0,0 +1 @@ +# Plugin Specification diff --git a/book/src/core-modules/constellation-generation/duration-based.md b/book/src/core-modules/constellation-generation/duration-based.md new file mode 100644 index 00000000..8767d431 --- /dev/null +++ b/book/src/core-modules/constellation-generation/duration-based.md @@ -0,0 +1,75 @@ +# Duration-based Constellation Generation + +This method also constructs the constellation based on an XML file and makes slight modifications to the previously described `constellation_generation/by_duration/constellation_configuration.py` and `constellation_generation/by_duration/orbit_configuration.py` source codes, enabling satellite network simulation with both the simulation duration and sampling interval specified simultaneously. + +## constellation_configuration.py + +The startup function of this script is `constellation_generation/by_duration/constellation_configuration`. + +### Function Parameters + +**Table: constellation_configuration** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :----------------: | :------------: | :------------: | :----------------------------------------------------------: | +| duration | int | second | Total network simulation time. In previous XML and TLE simulations, this value was fixed to the satellite orbit period. | +| dT | int | second | indicates how often timestamps are recorded, and this value must be less than the orbital period of the satellite | +| constellation_name | str | - | the name of the constellation, the value of this parameter must have the same name as the subfolder in "config/TLE_constellation/". The configuration file of the constellation named by that name is stored in a subfolder with the same name. | +| shell_index | int | - | The constellation shell required for simulation. Currently, this function only supports single-layer satellite network simulation. | + +### Key Differences from XML-based Generation + +The main difference from the standard XML-based generation is the addition of the `duration` parameter, which allows you to: + +- Specify a custom simulation timeframe rather than being limited to the satellite's orbital period +- Generate constellation data for exactly the time duration needed for your simulation +- Support time-constrained simulations where you don't need a full orbital period + +For a detailed explanation of the underlying mechanism, please refer to the [XML-based Generation](xml-based.md) section, as this method is a fine-tuned version based on it. + +## Case Study + +You can use the following example to construct a constellation for a specified simulation time. + +### Step 1: Set Parameters + +Set the parameters according to the instructions given in the table above: + +```python +duration = 100 +dT = 1 +cons_name = "Starlink" +shell_index = 1 +``` + +### Step 2: Call the Generation Function + +Call the `constellation_configuration` function to build the constellation topology: + +```python +constellation = constellation_configuration(duration, dT, cons_name, shell_index=1) +``` + +### Step 3: Use the Constellation + +After the above two steps, you have obtained a constellation configured for the specified duration. This constellation object can now be used with other StarPerf modules for: + +- Traffic generation +- Performance evaluation +- Energy consumption modeling +- Attack simulation + +## Use Cases + +Duration-based generation is particularly useful for: + +1. **Short-term simulations**: When you only need to analyze network behavior over a specific time window +2. **Resource-constrained environments**: When storage or computation limits prevent generating data for a full orbital period +3. **Targeted analysis**: When studying specific events or time periods in satellite network operation +4. **Rapid prototyping**: When you need quick results for initial testing or validation + +## Navigation + +- [Back to Constellation Generation Overview](overview.md) +- [Previous: TLE-based Generation](tle-based.md) +- [XML-based Generation](xml-based.md) diff --git a/book/src/core-modules/constellation-generation/overview.md b/book/src/core-modules/constellation-generation/overview.md new file mode 100644 index 00000000..c3985da2 --- /dev/null +++ b/book/src/core-modules/constellation-generation/overview.md @@ -0,0 +1,53 @@ +# Constellation Generation + +This module is used to generate and initialize satellite constellations. StarPerf 2.0 supports multiple ways of generating constellations: + +1. **XML-based Generation**: Use XML documents to build Walker-Ξ΄ or polar constellations +2. **TLE-based Generation**: Use TLE (Two-Line Element) data to build real constellations +3. **Duration-based Generation**: Build constellations with specified simulation duration and sampling interval + +## Overview + +The constellation generation module is part of the framework that implements constellation generation and constellation initialization. It provides the foundational capabilities for creating satellite network topologies that can be used with various evaluation and simulation modules. + +## Generation Methods + +### XML-based Constellation Generation + +This method uses XML configuration files to define constellation parameters such as: +- Orbital altitude and inclination +- Number of orbits and satellites per orbit +- Phase shift parameters +- Shell configurations + +See [XML-based Generation](xml-based.md) for detailed information. + +### TLE-based Constellation Generation + +This method uses real satellite data from TLE files to build constellations based on actual satellite positions. The process includes: +- Downloading TLE data from sources like CelesTrak +- Mapping satellites to shells based on launch information +- Determining satellite-to-orbit relationships +- Calculating satellite positions over time + +See [TLE-based Generation](tle-based.md) for detailed information. + +### Duration-based Constellation Generation + +This method builds constellations with both simulation duration and sampling interval specified simultaneously. It's based on XML configuration but allows for custom simulation timeframes rather than being limited to orbital periods. + +See [Duration-based Generation](duration-based.md) for detailed information. + +## Common Output + +All generation methods produce: +- A constellation object with shell, orbit, and satellite information +- Position data for each satellite at each timestamp +- Data stored in HDF5 (.h5) format under the `data/` directory + +## Navigation + +- [Back to Core Modules Overview](../overview.md) +- [XML-based Generation](xml-based.md) +- [TLE-based Generation](tle-based.md) +- [Duration-based Generation](duration-based.md) diff --git a/book/src/core-modules/constellation-generation/tle-based.md b/book/src/core-modules/constellation-generation/tle-based.md new file mode 100644 index 00000000..6bb825c9 --- /dev/null +++ b/book/src/core-modules/constellation-generation/tle-based.md @@ -0,0 +1,174 @@ +# TLE-based Constellation Generation + +This method uses five scripts to complete the constellation generation: `download_TLE_data.py`, `satellite_to_shell_mapping.py`, `satellite_to_orbit_mapping.py`, `get_satellite_position.py` and `constellation_configuration.py`. + +Overall, the constellation generated by this method can be divided into four stages: + +- **Stage 1**: download TLE data, and this function is implemented by `download_TLE_data.py`. +- **Stage 2**: determine the shell to which the satellite belongs, and this function is implemented by `satellite_to_shell_mapping.py`. +- **Stage 3**: determine the orbit to which the satellite belongs, and this function is implemented by `satellite_to_orbit_mapping.py`. +- **Stage 4**: save the satellite position information of each timeslot to a .h5 file, and this function is implemented by `get_satellite_position.py`. + +## download_TLE_data.py + +This method requires the use of two types of data to construct a constellation: +1. The emission information of the constellation satellites +2. The TLE of all satellites in the constellation + +### Data Sources + +**First Type - Launch Information**: In StarPerf 2.0, we provide Starlink satellite launch data by default, and these data are stored at: `config/TLE_constellation/Starlink/launches.xml`. + +Satellite launch data source: [https://en.wikipedia.org/wiki/List_of_Starlink_and_Starshield_launches#Launches](https://en.wikipedia.org/wiki/List_of_Starlink_and_Starshield_launches#Launches) + +**Second Type - TLE Data**: It can be downloaded from here: [https://celestrak.org/NORAD/elements/](https://celestrak.org/NORAD/elements/) + +### Function Parameters + +The startup function of this script is `download_TLE_data`. This function only accepts one parameter, which is the constellation name of the TLE data to be downloaded. + +### TLE Formats + +In order to facilitate the implementation of the following functions, here we will download two types of TLE, 2LE and JSON. + +#### 2LE Format + +TLE data containing only two rows of elements, such as: + +``` +1 44713U 19074A 24025.32501904 -.00001488 00000+0 -81005-4 0 9997 +2 44713 53.0536 62.8760 0001441 94.1015 266.0138 15.06396809232035 +``` + +#### JSON Format + +Parsing TLE data into JSON data, such as: + +```json +{ + "OBJECT_NAME": "STARLINK-1007", + "OBJECT_ID": "2019-074A", + "EPOCH": "2024-01-25T07:48:01.645056", + "MEAN_MOTION": 15.06396809, + "ECCENTRICITY": 0.0001441, + "INCLINATION": 53.0536, + "RA_OF_ASC_NODE": 62.876, + "ARG_OF_PERICENTER": 94.1015, + "MEAN_ANOMALY": 266.0138, + "EPHEMERIS_TYPE": 0, + "CLASSIFICATION_TYPE": "U", + "NORAD_CAT_ID": 44713, + "ELEMENT_SET_NO": 999, + "REV_AT_EPOCH": 23203, + "BSTAR": -8.1005e-5, + "MEAN_MOTION_DOT": -1.488e-5, + "MEAN_MOTION_DDOT": 0 +} +``` + +When the TLE data is downloaded successfully, the system will output prompt information on the terminal, such as: + +![TLE Download Success](../../images/tle_download_success.png) + +TLE data in these two formats will eventually be saved in the `config/TLE_constellation//tle.h5` file. + +**Note: When using TLE data to generate constellations, please ensure that your computer can be connected to the Internet because an Internet connection is required to download the data.** + +## satellite_to_shell_mapping.py + +This script establishes a corresponding relationship between each satellite described in the TLE data and the shell in which it is located, and the satellite's launch information is used to establish this relationship. + +### Implementation Mechanism + +In the TLE data in JSON format, there is a field named "OBJECT_ID", from which the launch batch number (COSPAR_ID) of the satellite can be obtained, combined with `config/TLE_constellation//launches.xml`, the corresponding relationship between COSPAR_ID, orbital altitude and orbital inclination can be used to infer the shell to which a satellite belongs. + +### Function Parameters + +The startup function of this script is `satellite_to_shell_mapping`. This function accepts only one parameter, the name of the constellation. + +## satellite_to_orbit_mapping.py + +Section 8.1.2.2 determines the shell to which the satellite belongs. This section is used to determine the orbit to which the satellite belongs. + +### Implementation Mechanism + +Sort the ascending node right ascension (raan) of all satellites in a shell, and then draw a distribution line chart of raan. The user observes the line chart and manually inputs the number of orbits. Subsequently, based on the number of orbits input by the user, we use the natural breakpoint method to divide these satellites into several orbits to determine the correspondence between satellites and orbits. + +When the script is executed, the program will output (some) line charts. The user needs to observe the line charts and determine the approximate number of tracks, and enter the approximate number into the program. For example, the following figure is a line chart output during program execution: + +![RAAN Distribution](../../images/raan_distribution.png) + +From this line chart, we can see that there are 5 values for raan, which means there are 5 tracks, so you need to manually enter 5 in the console: + +![Input Orbit Number](../../images/input_orbit_number.png) + +After you complete the input, the program will continue to run and use the natural breakpoint method to determine the orbit to which the satellite belongs based on the data you entered. A third-party library in Python called jenkspy has implemented the natural breakpoint method, so the jenkspy library is used here to determine the orbit to which the satellite belongs. + +Regarding the principles of the natural breakpoint method, you can refer here: [https://pbpython.com/natural-breaks.html](https://pbpython.com/natural-breaks.html) + +### Function Parameters + +The startup function of this script is `satellite_to_orbit_mapping`. This function only accepts one parameter, which is a shell class object. + +After the script is executed, the constellation has been generated. + +## get_satellite_position.py + +After the end of Section 8.1.2.3, the constellation has been generated. Now the position information (latitude, longitude and altitude) of each satellite needs to be saved, so the position of the satellite needs to be calculated based on TLE data. + +Here we use the skyfield library to calculate the satellite's position information. The specific implementation is: input the TLE data and the time corresponding to the TLE, and the skyfield library can parse out the longitude, latitude and altitude information of the satellite. + +Finally, we save the satellite position information of each timeslot into a .h5 file. The storage location of this file: `data/TLE_constellation/`. + +## constellation_configuration.py + +This script is used to call `download_TLE_data.py`, `satellite_to_shell_mapping.py`, `satellite_to_orbit_mapping.py` and `get_satellite_position.py` to complete the constellation initialization function. + +### Function Parameters + +The startup function of this script is `constellation_generation/by_TLE/constellation_configuration`. + +**Table: constellation_configuration** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :----------------: | :------------: | :------------: | :----------------------------------------------------------: | +| dT | int | second | indicates how often timestamps are recorded, and this value must be less than the orbital period of the satellite | +| constellation_name | str | - | the name of the constellation, the value of this parameter must have the same name as the subfolder in "config/TLE_constellation/". The configuration file of the constellation named by that name is stored in a subfolder with the same name. | + +When you need to use TLE data to generate a constellation, you only need to call this script to complete. + +## Case Study + +Now, we give an example of constellation generation using TLE data for easy understanding. + +### Step 1: Define Parameters + +We define the two function parameters as follows: + +```python +dT = 1000 +constellation_name = "Starlink" +``` + +### Step 2: Call the Generation Function + +We call the `constellation_configuration` function to generate the constellation: + +```python +# generate the constellations +constellation = constellation_configuration.constellation_configuration(dT, constellation_name) +``` + +### Step 3: View Results + +After the above two steps, we have obtained a constellation. Now print out some basic parameter information of the constellation, as follows (part): + +![TLE Constellation Generation Result](../../images/TLEconstellation_generation_test_result.png) + +The complete code of the above process can be found at: `samples/TLE_constellation/constellation_generation/constellation_generation_test.py`. + +## Navigation + +- [Back to Constellation Generation Overview](overview.md) +- [Previous: XML-based Generation](xml-based.md) +- [Next: Duration-based Generation](duration-based.md) diff --git a/book/src/core-modules/constellation-generation/tle-case-study.md b/book/src/core-modules/constellation-generation/tle-case-study.md new file mode 100644 index 00000000..d4b70890 --- /dev/null +++ b/book/src/core-modules/constellation-generation/tle-case-study.md @@ -0,0 +1 @@ +# Case Study diff --git a/book/src/core-modules/constellation-generation/tle-constellation-config.md b/book/src/core-modules/constellation-generation/tle-constellation-config.md new file mode 100644 index 00000000..ad69c146 --- /dev/null +++ b/book/src/core-modules/constellation-generation/tle-constellation-config.md @@ -0,0 +1 @@ +# constellation_configuration.py diff --git a/book/src/core-modules/constellation-generation/tle-download.md b/book/src/core-modules/constellation-generation/tle-download.md new file mode 100644 index 00000000..003dd6f3 --- /dev/null +++ b/book/src/core-modules/constellation-generation/tle-download.md @@ -0,0 +1 @@ +# download_TLE_data.py diff --git a/book/src/core-modules/constellation-generation/tle-orbit-mapping.md b/book/src/core-modules/constellation-generation/tle-orbit-mapping.md new file mode 100644 index 00000000..758e2ed7 --- /dev/null +++ b/book/src/core-modules/constellation-generation/tle-orbit-mapping.md @@ -0,0 +1 @@ +# satellite_to_orbit_mapping.py diff --git a/book/src/core-modules/constellation-generation/tle-position.md b/book/src/core-modules/constellation-generation/tle-position.md new file mode 100644 index 00000000..ff927a2e --- /dev/null +++ b/book/src/core-modules/constellation-generation/tle-position.md @@ -0,0 +1 @@ +# get_satellite_position.py diff --git a/book/src/core-modules/constellation-generation/tle-shell-mapping.md b/book/src/core-modules/constellation-generation/tle-shell-mapping.md new file mode 100644 index 00000000..235b0ae6 --- /dev/null +++ b/book/src/core-modules/constellation-generation/tle-shell-mapping.md @@ -0,0 +1 @@ +# satellite_to_shell_mapping.py diff --git a/book/src/core-modules/constellation-generation/xml-based.md b/book/src/core-modules/constellation-generation/xml-based.md new file mode 100644 index 00000000..99af5a8e --- /dev/null +++ b/book/src/core-modules/constellation-generation/xml-based.md @@ -0,0 +1,98 @@ +# XML-based Constellation Generation + +This method uses two scripts to complete the constellation generation: `constellation_generation/by_XML/constellation_configuration.py` and `constellation_generation/by_XML/orbit_configuration.py`. After these two scripts are executed, the constellation is generated. + +## constellation_configuration.py + +The startup function of this script is `constellation_configuration`. + +### Function Parameters + +**Table: constellation_configuration information** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :----------------: | :------------: | :------------: | :----------------------------------------------------------: | +| dT | int | second | indicates how often timestamps are recorded, and this value must be less than the orbital period of the satellite | +| constellation_name | str | - | the name of the constellation, and the value of this parameter must have the same name as an xml file in "config/XML_constellation". The xml file with the same name is the configuration file of the constellation named with that name | + +### Execution Process + +When executing the function `constellation_configuration`, the xml file under the "config/XML_constellation/" path will be loaded according to the parameter "constellation_name", that is: + +```python +xml_file_path = "config/XML_constellation/" + constellation_name + ".xml" +``` + +Afterwards, each shell of the constellation will be generated based on the xml data. Generating each shell consists of two stages. + +#### Stage 1: Generating Basic Parameters + +Generating the basic parameters of the shell, such as orbital altitude, orbital period, orbital inclination, number of orbits, number of satellites in each orbit, etc. This stage can be completed directly using xml data. + +#### Stage 2: Generating Orbits and Satellites + +Generating orbits and satellites in the shell. This stage is implemented by two Python third-party libraries, skyfield and sgp4. The specific implementation of this part is in `orbit_configuration.py`. You only need to just call this script in `constellation_configuration.py`. + +After the completion of these two stages, the target constellation initialization task has been completed. At this time, the position information of each satellite in the constellation at each moment is saved in an h5 file under "data/XML_constellation". + +**Note: The number of constellation moments is determined by the parameter dT and the orbital period. That is, a total of `(int)(orbit_cycle / dT)` satellite position data needs to be saved to the h5 file.** + +Finally, the return value of this function represents the generated constellation, which is a constellation object. + +## orbit_configuration.py + +The startup function of this script is `constellation_generation/by_XML/orbit_configuration`. + +### Function Parameters + +**Table: orbit_configuration information** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :------------: | :------------: | :------------: | :----------------------------------------------------------: | +| dT | int | second | indicates how often timestamps are recorded, and this value must be less than the orbital period of the satellite | +| sh | shell | - | shell to generate orbits and satellites | + +### Execution Process + +When this function is executed, the system will generate the Kepler parameters of each orbit based on the existing parameters of "sh" (number of orbits, orbital inclination, number of satellites in each orbit, etc.). Then, in-orbit satellites are generated based on the generated orbits. This process uses the skyfield and sgp4 libraries. + +This function is called by `constellation_configuration.py` and is responsible for completing the functions of **Stage 2** described above. Therefore, this function has no return value. After execution, continue to execute `constellation_configuration.py`. + +## Case Study + +Now, we give an example of Walker-Ξ΄ constellation generation and initialization to facilitate your understanding. + +### Step 1: Define Parameters + +We define the two function parameters as follows: + +```python +dT = 5730 +constellation_name = "Starlink" +``` + +### Step 2: Call the Generation Function + +We call the `constellation_configuration` function to generate the constellation: + +```python +# generate the constellations +constellation = constellation_configuration.constellation_configuration( + dT=dT, + constellation_name=constellation_name +) +``` + +### Step 3: View Results + +After the above two steps, we have obtained a constellation. Now print out some basic parameter information of the constellation, as follows (part): + +![XML Constellation Generation Result](../../images/XMLconstellation_generation_test_result.png) + +The complete code of the above process can be found at: `samples/XML_constellation/constellation_generation/constellation_generation_test.py`. + +## Navigation + +- [Back to Constellation Generation Overview](overview.md) +- [Next: TLE-based Generation](tle-based.md) +- [Duration-based Generation](duration-based.md) diff --git a/book/src/core-modules/constellation-generation/xml-case-study.md b/book/src/core-modules/constellation-generation/xml-case-study.md new file mode 100644 index 00000000..d4b70890 --- /dev/null +++ b/book/src/core-modules/constellation-generation/xml-case-study.md @@ -0,0 +1 @@ +# Case Study diff --git a/book/src/core-modules/constellation-generation/xml-constellation-config.md b/book/src/core-modules/constellation-generation/xml-constellation-config.md new file mode 100644 index 00000000..ad69c146 --- /dev/null +++ b/book/src/core-modules/constellation-generation/xml-constellation-config.md @@ -0,0 +1 @@ +# constellation_configuration.py diff --git a/book/src/core-modules/constellation-generation/xml-orbit-config.md b/book/src/core-modules/constellation-generation/xml-orbit-config.md new file mode 100644 index 00000000..ffd3e8d3 --- /dev/null +++ b/book/src/core-modules/constellation-generation/xml-orbit-config.md @@ -0,0 +1 @@ +# orbit_configuration.py diff --git a/book/src/core-modules/entity/overview.md b/book/src/core-modules/entity/overview.md new file mode 100644 index 00000000..07dd0c5c --- /dev/null +++ b/book/src/core-modules/entity/overview.md @@ -0,0 +1 @@ +# Overview diff --git a/book/src/core-modules/evaluation/bentpipe-bandwidth.md b/book/src/core-modules/evaluation/bentpipe-bandwidth.md new file mode 100644 index 00000000..cfd135ea --- /dev/null +++ b/book/src/core-modules/evaluation/bentpipe-bandwidth.md @@ -0,0 +1 @@ +# Bandwidth diff --git a/book/src/core-modules/evaluation/bentpipe-coverage.md b/book/src/core-modules/evaluation/bentpipe-coverage.md new file mode 100644 index 00000000..acd79d20 --- /dev/null +++ b/book/src/core-modules/evaluation/bentpipe-coverage.md @@ -0,0 +1 @@ +# Coverage diff --git a/book/src/core-modules/evaluation/bentpipe-delay.md b/book/src/core-modules/evaluation/bentpipe-delay.md new file mode 100644 index 00000000..24057c82 --- /dev/null +++ b/book/src/core-modules/evaluation/bentpipe-delay.md @@ -0,0 +1 @@ +# Delay diff --git a/book/src/core-modules/evaluation/isl-bandwidth.md b/book/src/core-modules/evaluation/isl-bandwidth.md new file mode 100644 index 00000000..cfd135ea --- /dev/null +++ b/book/src/core-modules/evaluation/isl-bandwidth.md @@ -0,0 +1 @@ +# Bandwidth diff --git a/book/src/core-modules/evaluation/isl-betweenness.md b/book/src/core-modules/evaluation/isl-betweenness.md new file mode 100644 index 00000000..8eff045d --- /dev/null +++ b/book/src/core-modules/evaluation/isl-betweenness.md @@ -0,0 +1 @@ +# Betweenness diff --git a/book/src/core-modules/evaluation/isl-coverage.md b/book/src/core-modules/evaluation/isl-coverage.md new file mode 100644 index 00000000..acd79d20 --- /dev/null +++ b/book/src/core-modules/evaluation/isl-coverage.md @@ -0,0 +1 @@ +# Coverage diff --git a/book/src/core-modules/evaluation/isl-delay.md b/book/src/core-modules/evaluation/isl-delay.md new file mode 100644 index 00000000..24057c82 --- /dev/null +++ b/book/src/core-modules/evaluation/isl-delay.md @@ -0,0 +1 @@ +# Delay diff --git a/book/src/core-modules/evaluation/overview.md b/book/src/core-modules/evaluation/overview.md new file mode 100644 index 00000000..52133d5c --- /dev/null +++ b/book/src/core-modules/evaluation/overview.md @@ -0,0 +1,171 @@ +# Constellation Evaluation + +Constellation performance evaluation is generally divided into two categories: with ISL and without ISL. The former is used in +Grid and other modes and includes four evaluation indicators: bandwidth, betweenness, coverage and delay. The latter is used in bent-pipe mode and includes three evaluation indicators: bandwidth, coverage and delay. + +## Overview + +The evaluation module provides comprehensive performance metrics for satellite constellations. Different metrics are available depending on whether the constellation operates with Inter-Satellite Links (ISLs) or in bent-pipe mode. + +## Evaluation Modes + +### Performance Evaluation with ISL + +In this section, we take the +Grid connection mode as an example to evaluate the constellation performance. + +#### Bandwidth + +First, given a shell in a constellation, as well as two ground station objects source and destination, pass in a parameter Ξ», and then calculate the bandwidth between the source and destination. The calculation of the bandwidth value refers to the total bandwidth of all disjoint paths from the source to the destination whose delay time does not exceed Ξ» times the shortest delay time. Ξ» is a floating point number not less than 1 (that is, the minimum value of Ξ» is 1). + +**Table: bandwidth function attributes list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :----------------: | :------------: | :------------: | :----------------------------------------------------------: | +| constellation_name | str | - | the name of the constellation, such as "Starlink" | +| source | user | - | the source of the communication pair | +| target | user | - | the destination of the communication pair | +| sh | shell | - | a shell in the constellation | +| Ξ» | float | - | the maximum multiple of the minimum delay time allowed from source to target. The smaller the Ξ» value, the fewer the number of paths from source to target. When Ξ»=1, only one path meets the requirements (i.e. the shortest path). | +| isl_capacity | float | Gbps | the capacity of a single ISL, such as 5Gbps | +| dT | int | second | how often a timeslot is recorded | + +Calculate the bandwidth between source and target in each timeslot, and finally average it to be the final bandwidth between source and target, and return this final calculation result. + +#### Betweenness + +Betweenness is a metric that describes the centrality in a graph based on shortest paths, and it is widely used in telecommunications networks, e.g., a node with higher betweenness centrality would have more traffic passing through that node. Moreover, a node with a high betweenness centrality may also be a potential bottleneck node, since the failure of this node will affect all flows relying on it. In this function we will evaluate the betweenness of each satellite in the constellation. + +Specifically, the betweenness of a satellite sat is calculated as: + +$$ +betweenness(sat) = \sum_{s \ne d \ne sat} \frac{p_{sd}(sat)}{p_{sd}} +$$ + +where $p_{sd}$ is the total number of the shortest paths from source $s$ to destination $d$, and $p_{sd}(sat)$ is the number of those paths that pass through $sat$. + +**Table: betweenness function attributes list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :----------------: | :------------: | :------------: | :-----------------------------------------------: | +| constellation_name | str | - | the name of the constellation, such as "Starlink" | +| sh | shell | - | a shell in the constellation | +| t | int | - | a certain time slot (timeslot) | + +After the calculation is completed, a list will eventually be returned. Each element in the list is of type float, representing the betweenness of each satellite. + +#### Coverage + +Calculation method: Divide the longitude of the earth's surface every $\alpha$ and the latitude every $\alpha$, thus obtaining $\frac{180}{\alpha} \times \frac{360}{\alpha}$ fragments. Each fragment represents a certain area of the earth's surface. The default value of Ξ± is 10Β°. + +**Table: coverage function attributes list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :----------------: | :------------: | :------------: | :----------------------------------------------------------: | +| constellation_name | str | - | the name of the constellation, such as "Starlink" | +| dT | int | second | how often a timeslot is recorded | +| sh | shell | - | a shell in the constellation | +| tile_size(Ξ±) | float | degree | the size of the square block on the earth's surface, the default is to cut every 10Β°, that is, each block occupies 10Β° longitude and 10Β° latitude. | +| maximum_depression | float | degree | the maximum depression angle of the satellite, the default value is 56.5Β° | +| minimum_elevation | float | degree | the minimum elevation angle of the ground observation point, the default value is 25Β° | + +This function calculates the coverage of each timeslot, and finally stores the coverage of each timeslot into a list variable and returns it. + +#### Delay + +This function is used to calculate the delay time of two communication endpoints, that is, the total time of sending a packet from the source to the destination, and the total time of sending a packet from the destination to the source (RTT time). + +**Table: delay function attributes list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :----------------: | :------------: | :------------: | :-----------------------------------------------: | +| constellation_name | str | - | the name of the constellation, such as "Starlink" | +| source | user | - | source endpoint of the communication pair | +| target | user | - | destination endpoint of the communication pair | +| dT | int | second | how often a timeslot is recorded | +| sh | shell | - | a shell in the constellation | + +This function calculates the delay time of each timeslot, and finally stores the delay time of each timeslot into a list variable and returns it. + +### Performance Evaluation without ISL + +In this section, we evaluate the performance of constellations without ISL, i.e. the performance of constellations in bent-pipe operating mode. + +#### Bandwidth + +Calculation method: When the bent-pipe mode communicates between two ends (denoted as end A and end B), end A selects a satellite in the sky as a relay (denoted as satellite 1) according to a certain strategy, and end B selects a satellite in the sky as a relay according to a certain strategy (denoted as satellite 2). Assume that there are $n$ GSs within the visible range of satellite 1, and the bandwidth of each GS is $P$; there are $m$ GSs within the visible range of satellite 2, and the bandwidth of each GS is $P$. Therefore, the bandwidth of satellite 1 β†’ satellite 2 can be expressed as $n \times P$, and the bandwidth of satellite 2 β†’ satellite 1 can be expressed as $m \times P$. Since the communication is bidirectional, the communication bandwidth between A and B is $\min\{n \times P, m \times P\}$. The above calculation is performed for each timeslot within the satellite orbit period. Finally, the average of all timeslot values can be used as the bent-pipe bandwidth for communication between A and B. + +**Table: bandwidth function attributes list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :-----------------: | :------------: | :------------: | :----------------------------------------------------------: | +| source | user | - | the source of the communication pair | +| target | user | - | the destination of the communication pair | +| dT | int | second | how often a timeslot is recorded | +| sh | shell | - | a shell in the constellation | +| ground_station_file | str | - | constellation ground station file path (the path is calculated from the root directory of the project) | +| minimum_elevation | float | degree | the minimum elevation angle of the ground users | +| GS_capacity | float | Gbps | the GS capacity of each ground station, such as 10 Gbps | + +Calculate the bandwidth between source and target in each timeslot, and finally average it to be the final bandwidth between source and target, and return this final calculation result. + +#### Coverage + +Calculation method: In bent-pipe mode, the coverage of the constellation is not only related to the satellite itself, but also to the GS. If a user is in an area where a satellite can be seen overhead, but there is no GS within the visible range of the satellite, then the area where the user is located is said to be not covered by bent-pipe. + +Specifically, the coverage rate in bent-pipe mode can be calculated as follows: First, divide the earth's surface into several tiles, for example, every 10Β° interval according to the longitude and latitude, so that you will get 18Γ—36 tiles. Then select a point (latitude and longitude) in each tile as the user's position, take the user as the perspective, calculate all satellites visible to the user (note the set of these satellites as S), traverse all satellites in the S set, as long as at least one satellite in the S set has a GS in its visible field of view, the tile is considered to be covered. Perform this operation on all tiles, and finally divide the number of covered tiles by the total number of tiles, which is the coverage rate of the constellation under the current timeslot. Perform the above operation on all timeslots to obtain the constellation coverage under each timeslot, and finally average the value and return it as the final constellation coverage. + +**Table: coverage function attributes list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :-----------------: | :------------: | :------------: | :----------------------------------------------------------: | +| dT | int | second | how often a timeslot is recorded | +| sh | shell | - | a shell in the constellation | +| ground_station_file | str | - | constellation ground station file path (the path is calculated from the root directory of the project) | +| minimum_elevation | float | degree | the minimum elevation angle of the ground users | +| tile_size | float | degree | the size of the square block on the earth's surface, the default is to cut every 10Β°, that is, each block occupies 10Β° longitude and 10Β° latitude. | + +This function calculates the coverage of each timeslot, and finally stores the coverage of each timeslot into a list variable and returns it. + +#### Delay + +Calculation method: When the bent-pipe mode communicates between two terminals (denoted as terminal A and terminal B), the process is: terminal A β†’ satellite 1 β†’ ground station A β†’ POP point 1 β†’ terminal B, or terminal B β†’ Satellite 2 β†’ Ground station B β†’ POP point 2 β†’ Terminal A. Therefore, if you want to calculate the delay between terminal A and terminal B in bent-pipe mode, you can calculate the delay between terminal A β†’ satellite 1 β†’ ground station A β†’ POP point 1 β†’ POP point 2 β†’ ground station B β†’ satellite 2 β†’ terminal B β†’ satellite 2 β†’ ground station B β†’ POP point 2 β†’ POP point 1 β†’ ground station A β†’ satellite 1 β†’ terminal A, use this delay time to represent the bent-pipe delay between terminal A and terminal B. Among them, when calculating the delay between POP point 1 β†’ POP point 2 or POP point 2 β†’ POP point 1, it is expressed by dividing the great circle distance on the earth's surface by a certain speed. + +**Table: delay function attributes list** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :-----------------: | :------------: | :------------: | :----------------------------------------------------------: | +| source | user | - | the source of the communication pair | +| target | user | - | the destination of the communication pair | +| dT | int | second | how often a timeslot is recorded | +| sh | shell | - | a shell in the constellation | +| ground_station_file | str | - | constellation ground station file path (the path is calculated from the root directory of the project) | +| POP_file | str | - | satellite constellation ground POP point data file | +| Ξ± | float | - | the great circle distance coefficient between the source and target points | +| Ξ² | float | - | the communication speed between source and target. The speed of light in vacuum is c, but the speed of communication between source and target may not be c. Therefore, the speed of light c multiplied by the speed coefficient Ξ² represents the final communication speed from source to target. | +| minimum_elevation | float | degree | the minimum elevation angle of the ground users | + +This function calculates the delay time of each timeslot, and finally stores the delay time of each timeslot into a list variable and returns it. + +## Use Cases + +The evaluation module is essential for: + +1. **Performance Comparison**: Comparing different constellation designs or configurations +2. **Bottleneck Identification**: Finding potential performance bottlenecks using betweenness +3. **Coverage Analysis**: Ensuring adequate service coverage for target regions +4. **Quality of Service**: Validating delay and bandwidth requirements are met +5. **Design Optimization**: Iterating on constellation parameters to improve metrics + +## Integration with Other Modules + +The evaluation module works in conjunction with: + +- **Connectivity Module**: Requires established ISL topology for ISL-based metrics +- **Beam Placement Module**: Affects coverage calculations +- **Routing Module**: Influences delay and bandwidth calculations +- **Traffic Module**: Provides realistic load for capacity analysis + +## Navigation + +- [Back to Core Modules Overview](../overview.md) +- [Previous: Connectivity](../connectivity/overview.md) +- [Beam Placement](../beam-placement/overview.md) diff --git a/book/src/core-modules/evaluation/with-isl.md b/book/src/core-modules/evaluation/with-isl.md new file mode 100644 index 00000000..fac3438f --- /dev/null +++ b/book/src/core-modules/evaluation/with-isl.md @@ -0,0 +1 @@ +# With ISL diff --git a/book/src/core-modules/evaluation/without-isl.md b/book/src/core-modules/evaluation/without-isl.md new file mode 100644 index 00000000..b062047e --- /dev/null +++ b/book/src/core-modules/evaluation/without-isl.md @@ -0,0 +1 @@ +# Without ISL (Bent-pipe) diff --git a/book/src/core-modules/overview.md b/book/src/core-modules/overview.md new file mode 100644 index 00000000..22574152 --- /dev/null +++ b/book/src/core-modules/overview.md @@ -0,0 +1,44 @@ +# Kernel Module: src/ + +This module is the kernel code module of StarPerf 2.0, which stores the system's "framework + plug-in". The architecture of this module is as follows: + +![Kernel Module Architecture](../images/new_kernel_arch.png) + +## Module Overview + +The function of each module in the above figure are as follows: + +**Table: Kernel Module Submodules and Functions** + +| Module | Function | +| :-----------------------: | :----------------------------------------------------------: | +| constellation_generation/ | part of the "framework" that implements constellation generation and constellation initialization. | +| standalone_module/ | Provide some independent function modules, such as calculating the length of satellite time that users can see. | +| TLE_constellation/ | Construct constellations using TLE data. | +| XML_constellation/ | Construct constellations using XML data. | + +## Core Functional Modules + +The core functional modules available for both XML and TLE constellations are shown in the following table: + +**Table: Core Functional Modules and Functions** + +| Module | Function | +| :----------------: | :----------------------------------------------------------: | +| beamplacement/ | **constellation_beamplacement**: implement part of the "framework" related to beam placement, as well as plug-ins related to beam placement algorithms. | +| connectivity/ | **constellation_connectivity**: implements parts of the "framework" related to the connectivity mode between satellites in the constellation, as well as plug-ins for the connectivity mode. | +| evaluation/ | **constellation_evaluation**: implement part of the "framework" related to constellation performance evaluation, such as delay, bandwidth, coverage, etc. | +| entity/ | **constellation_entity**: the entity classes in StarPerf 2.0 are defined, such as orbit, satellite, ground stations, etc., and this module is part of the "framework". | +| highsurvivability/ | **constellation_highsurvivability**: implement part of the "framework" related to the high survivability aspect of the constellation, as well as some constellation damage model plug-ins. | +| routing/ | **constellation_routing**: implements part of the "framework" for constellation routing, as well as some routing strategy plug-ins. | +| traffic/ | **constellation_traffic**: implements part of the "framework" for traffic generation, as well as traffic model plug-ins. | +| energy/ | **constellation_energy**: implements part of the "framework" for energy consumption modeling, as well as energy model plug-ins. | +| attack/ | **constellation_attack**: implements part of the "framework" for attack simulation, as well as attack model plug-ins. | + +## Navigation + +- [Constellation Generation](constellation-generation/overview.md) +- [Standalone Modules](standalone-modules/satellite-visibility.md) +- [Beam Placement](beam-placement/overview.md) +- [Connectivity](connectivity/overview.md) +- [Evaluation](evaluation/overview.md) diff --git a/book/src/core-modules/routing/framework.md b/book/src/core-modules/routing/framework.md new file mode 100644 index 00000000..2660e90d --- /dev/null +++ b/book/src/core-modules/routing/framework.md @@ -0,0 +1 @@ +# Framework diff --git a/book/src/core-modules/routing/overview.md b/book/src/core-modules/routing/overview.md new file mode 100644 index 00000000..07dd0c5c --- /dev/null +++ b/book/src/core-modules/routing/overview.md @@ -0,0 +1 @@ +# Overview diff --git a/book/src/core-modules/routing/plugins.md b/book/src/core-modules/routing/plugins.md new file mode 100644 index 00000000..8efd0556 --- /dev/null +++ b/book/src/core-modules/routing/plugins.md @@ -0,0 +1 @@ +# Plugin Specification diff --git a/book/src/core-modules/standalone-modules/satellite-visibility.md b/book/src/core-modules/standalone-modules/satellite-visibility.md new file mode 100644 index 00000000..934dea88 --- /dev/null +++ b/book/src/core-modules/standalone-modules/satellite-visibility.md @@ -0,0 +1,72 @@ +# Standalone Modules + +This module is used to implement some relatively independent functions and can be used by users as needed. + +## Satellite Visible Time Calculation + +In some cases, it may be necessary to calculate the time a satellite is visible to the user. For example, we need to calculate how long the satellite can be observed by ground users in the scenario shown in the figure below: + +![Satellite Visibility Time](../../images/satellite_visibility_time.png) + +This is a simple geometric calculation function implemented by `src/standalone_module/satellite_visibility_time.py`. + +### Function Parameters + +The startup function of this script is `satellite_visibility_time`. + +**Table: satellite_visibility_time** + +| Parameter Name | Parameter Type | Parameter Unit | Parameter Meaning | +| :------------: | :------------: | :------------: | :----------------------------------------------------------: | +| ΞΈ | float | degree | the lowest elevation angle at which the user can see the satellite | +| h | float | km | the height of a satellite's orbit above the earth's surface | + +### Implementation + +This function performs a geometric calculation based on the satellite's orbital height and the minimum elevation angle at which a ground user can observe the satellite. It returns the duration for which the satellite remains visible to the ground user. + +The calculation takes into account: +- The Earth's radius +- The satellite's orbital altitude +- The minimum elevation angle constraint +- The satellite's orbital velocity + +## Case Study + +Now, we give an example of calculating the satellite time visible to ground users for easier understanding: + +### Example Code + +```python +satellite_visibility_time(ΞΈ=25, h=550) +``` + +### Results + +The results of executing the above code are as follows: + +![Satellite Visibility Time Result](../../images/satellite_visibility_time_result.png) + +The complete code of the above process can be found at: `samples/standalone_module/standalone_module_test_cases.py`. + +## Use Cases + +The satellite visibility time calculation is useful for: + +1. **Coverage Analysis**: Understanding how long users in different locations can maintain connectivity +2. **Handover Planning**: Determining when satellite handovers need to occur +3. **Link Budget Calculations**: Estimating available communication windows +4. **QoS Guarantees**: Evaluating service availability for different user locations + +## Mathematical Background + +The visibility time depends on several geometric factors: + +- **Elevation Angle (ΞΈ)**: Lower elevation angles provide longer visibility but suffer from atmospheric effects and potential obstructions +- **Orbital Height (h)**: Higher satellites are visible for longer periods but have longer propagation delays +- **Earth's Geometry**: The spherical nature of Earth limits the maximum possible visibility time + +## Navigation + +- [Back to Core Modules Overview](../overview.md) +- [Constellation Generation Overview](../constellation-generation/overview.md) diff --git a/book/src/core-modules/survivability/framework.md b/book/src/core-modules/survivability/framework.md new file mode 100644 index 00000000..2660e90d --- /dev/null +++ b/book/src/core-modules/survivability/framework.md @@ -0,0 +1 @@ +# Framework diff --git a/book/src/core-modules/survivability/overview.md b/book/src/core-modules/survivability/overview.md new file mode 100644 index 00000000..07dd0c5c --- /dev/null +++ b/book/src/core-modules/survivability/overview.md @@ -0,0 +1 @@ +# Overview diff --git a/book/src/core-modules/survivability/plugins.md b/book/src/core-modules/survivability/plugins.md new file mode 100644 index 00000000..8efd0556 --- /dev/null +++ b/book/src/core-modules/survivability/plugins.md @@ -0,0 +1 @@ +# Plugin Specification diff --git a/book/src/examples/beam-placement.md b/book/src/examples/beam-placement.md new file mode 100644 index 00000000..28e28102 --- /dev/null +++ b/book/src/examples/beam-placement.md @@ -0,0 +1 @@ +# Beam Placement Example diff --git a/book/src/examples/connectivity.md b/book/src/examples/connectivity.md new file mode 100644 index 00000000..aa86fcfc --- /dev/null +++ b/book/src/examples/connectivity.md @@ -0,0 +1 @@ +# Connectivity Example diff --git a/book/src/examples/evaluation.md b/book/src/examples/evaluation.md new file mode 100644 index 00000000..3cd7c0b0 --- /dev/null +++ b/book/src/examples/evaluation.md @@ -0,0 +1 @@ +# Performance Evaluation Example diff --git a/book/src/examples/overview.md b/book/src/examples/overview.md new file mode 100644 index 00000000..9c04e28e --- /dev/null +++ b/book/src/examples/overview.md @@ -0,0 +1,320 @@ +# Examples Overview + +This section provides practical examples demonstrating how to use StarPerf for various simulation scenarios. + +## Available Examples + +StarPerf includes comprehensive examples in the `samples/` directory, organized by functionality: + +### Constellation Generation Examples + +Learn how to create satellite constellations: +- [XML Constellation Example](./xml-constellation.md) - Building theoretical constellations +- [TLE Constellation Example](./tle-constellation.md) - Working with real constellation data + +### Functional Module Examples + +Explore specific features: +- [Beam Placement Example](./beam-placement.md) - Implementing beam placement algorithms +- [Connectivity Example](./connectivity.md) - Configuring satellite connectivity modes +- [Performance Evaluation Example](./evaluation.md) - Measuring constellation performance + +### Advanced Examples + +Specialized use cases: +- [Traffic Generation Example](./traffic-generation.md) - Simulating network traffic patterns +- [Attack Simulation Example](./attack-simulation.md) - Modeling security threats + +## Example Directory Structure + +``` +samples/ +β”œβ”€β”€ XML_constellation/ # XML-based constellation examples +β”‚ β”œβ”€β”€ constellation_generation/ +β”‚ β”‚ └── constellation_generation_test.py +β”‚ β”œβ”€β”€ beam_placement/ +β”‚ β”‚ └── random_placement.py +β”‚ β”œβ”€β”€ positive_Grid/ +β”‚ β”‚ └── grid_connectivity.py +β”‚ └── evaluation/ +β”‚ └── performance_metrics.py +β”œβ”€β”€ TLE_constellation/ # TLE-based constellation examples +β”‚ β”œβ”€β”€ constellation_generation/ +β”‚ β”‚ └── constellation_generation_test.py +β”‚ β”œβ”€β”€ beam_placement/ +β”‚ β”‚ └── random_placement.py +β”‚ └── positive_Grid/ +β”‚ └── grid_connectivity.py +β”œβ”€β”€ duration_constellation/ # Duration-based examples +β”‚ └── duration_test.py +β”œβ”€β”€ standalone_module/ # Independent function examples +β”‚ └── standalone_module_test_cases.py +β”œβ”€β”€ traffic/ # Traffic simulation examples +β”‚ └── traffic_generation_cases.py +└── attack/ # Attack simulation examples + └── ICARUS/ + └── single_link.py +``` + +## Running Examples + +All examples can be run using the `uv run` command: + +```bash +# XML constellation generation +uv run python samples/XML_constellation/constellation_generation/constellation_generation_test.py + +# TLE constellation generation +uv run python samples/TLE_constellation/constellation_generation/constellation_generation_test.py + +# Beam placement +uv run python samples/XML_constellation/beam_placement/random_placement.py + +# Traffic generation +uv run python samples/traffic/traffic_generation_cases.py +``` + +## Common Patterns + +### Basic Simulation Pattern + +Most examples follow this structure: + +```python +# 1. Import required modules +from src.constellation_generation.by_XML import constellation_configuration +from src.XML_constellation.constellation_connectivity import connectivity_mode_plugin_manager +from src.XML_constellation.constellation_evaluation import evaluation + +# 2. Define parameters +dT = 5730 +constellation_name = "Starlink" + +# 3. Generate constellation +constellation = constellation_configuration.constellation_configuration( + dT=dT, + constellation_name=constellation_name +) + +# 4. Configure connectivity +conn_manager = connectivity_mode_plugin_manager.connectivity_mode_plugin_manager() +conn_manager.set_connection_mode("positive_Grid") +conn_manager.execute_connection_policy(constellation=constellation, dT=dT) + +# 5. Evaluate performance +results = evaluation.coverage( + constellation_name=constellation_name, + dT=dT, + sh=constellation.shells[0] +) + +# 6. Process and display results +print(f"Average coverage: {sum(results)/len(results):.2f}") +``` + +### Plugin Usage Pattern + +When using plugins (beam placement, connectivity, routing): + +```python +# 1. Initialize plugin manager +manager = plugin_manager_class() + +# 2. Set desired plugin +manager.set_policy("plugin_name") + +# 3. Execute plugin with parameters +result = manager.execute_policy( + constellation=constellation, + # ... other parameters +) + +# 4. Process results +# ... work with returned data +``` + +## Example Workflows + +### Workflow 1: Basic Constellation Analysis + +```python +# Generate constellation β†’ Configure connectivity β†’ Evaluate performance + +from src.constellation_generation.by_XML import constellation_configuration +from src.XML_constellation.constellation_connectivity import connectivity_mode_plugin_manager +from src.XML_constellation.constellation_evaluation import evaluation + +# Generate +constellation = constellation_configuration.constellation_configuration( + dT=5730, + constellation_name="Starlink" +) + +# Connect +conn_mgr = connectivity_mode_plugin_manager.connectivity_mode_plugin_manager() +conn_mgr.execute_connection_policy(constellation=constellation, dT=5730) + +# Evaluate +coverage = evaluation.coverage( + constellation_name="Starlink", + dT=5730, + sh=constellation.shells[0] +) +``` + +### Workflow 2: Comparative Analysis + +```python +# Compare multiple constellations or configurations + +constellations = ["Starlink", "OneWeb", "Telesat"] +results = {} + +for const_name in constellations: + constellation = constellation_configuration.constellation_configuration( + dT=5730, + constellation_name=const_name + ) + + coverage = evaluation.coverage( + constellation_name=const_name, + dT=5730, + sh=constellation.shells[0] + ) + + results[const_name] = { + 'avg_coverage': sum(coverage) / len(coverage), + 'num_satellites': sum(len(sh.satellites) for sh in constellation.shells) + } + +# Display comparison +for name, data in results.items(): + print(f"{name}: {data['num_satellites']} satellites, {data['avg_coverage']:.2f} coverage") +``` + +### Workflow 3: Time-Series Analysis + +```python +# Analyze performance over time + +import matplotlib.pyplot as plt + +# Generate constellation +constellation = constellation_configuration.constellation_configuration( + dT=1000, # Record every 1000 seconds + constellation_name="Starlink" +) + +# Configure connectivity +conn_mgr.execute_connection_policy(constellation=constellation, dT=1000) + +# Calculate coverage for each timeslot +coverage_over_time = evaluation.coverage( + constellation_name="Starlink", + dT=1000, + sh=constellation.shells[0] +) + +# Plot results +plt.plot(coverage_over_time) +plt.xlabel('Timeslot') +plt.ylabel('Coverage (%)') +plt.title('Starlink Coverage Over Time') +plt.savefig('coverage_analysis.png') +``` + +## Customizing Examples + +### Modifying Parameters + +Key parameters you can adjust: + +```python +# Time parameters +dT = 1000 # Timestamp interval (seconds) +duration = 86400 # Simulation duration (seconds) + +# Spatial parameters +h3_resolution = 2 # Grid resolution (0-4) +minimum_elevation = 25 # Minimum elevation angle (degrees) +tile_size = 10 # Coverage tile size (degrees) + +# Constellation parameters +constellation_name = "Starlink" +shell_index = 0 # Which shell to analyze + +# Connectivity parameters +isl_capacity = 5.0 # ISL bandwidth (Gbps) +connection_mode = "positive_Grid" + +# Beam parameters +antenna_count_per_satellite = 8 +beam_placement_policy = "random_placement" +``` + +### Adding Custom Logic + +You can extend examples with custom analysis: + +```python +# Custom metric calculation +def calculate_custom_metric(constellation, dT): + """Calculate a custom performance metric""" + # Your custom logic here + metric_values = [] + + for timeslot in range(num_timeslots): + # Compute metric for this timeslot + value = compute_metric(constellation, timeslot) + metric_values.append(value) + + return metric_values + +# Use in your simulation +results = calculate_custom_metric(constellation, dT) +print(f"Custom metric average: {sum(results)/len(results):.2f}") +``` + +## Tips for Using Examples + +1. **Start Simple**: Begin with basic constellation generation examples +2. **Read the Code**: Examples include comments explaining each step +3. **Modify Parameters**: Experiment with different configurations +4. **Compare Results**: Run multiple examples to understand differences +5. **Check Output**: Look in `data/` directory for generated files +6. **Use Visualization**: Combine with visualization to see results visually + +## Common Issues and Solutions + +### Issue: Example Fails to Run + +**Solution**: Ensure all dependencies are installed: +```bash +uv sync +``` + +### Issue: Missing Configuration Files + +**Solution**: Verify configuration files exist: +```bash +ls config/XML_constellation/ +ls config/TLE_constellation/ +``` + +### Issue: Out of Memory + +**Solution**: For large constellations, increase dT or reduce simulation duration: +```python +dT = 5730 # Larger interval = fewer timeslots = less memory +``` + +## Next Steps + +Dive into specific examples: +- [XML Constellation Example](./xml-constellation.md) - Start here for beginners +- [TLE Constellation Example](./tle-constellation.md) - Work with real data +- [Performance Evaluation Example](./evaluation.md) - Analyze results + +Or explore: +- [Core Modules](../core-modules/overview.md) - Understand the underlying systems +- [API Reference](../api-reference/introduction.md) - Detailed interface documentation diff --git a/book/src/examples/tle-constellation.md b/book/src/examples/tle-constellation.md new file mode 100644 index 00000000..b6017057 --- /dev/null +++ b/book/src/examples/tle-constellation.md @@ -0,0 +1 @@ +# TLE Constellation Example diff --git a/book/src/examples/xml-constellation.md b/book/src/examples/xml-constellation.md new file mode 100644 index 00000000..a9899be6 --- /dev/null +++ b/book/src/examples/xml-constellation.md @@ -0,0 +1 @@ +# XML Constellation Example diff --git a/book/src/getting-started/installation.md b/book/src/getting-started/installation.md new file mode 100644 index 00000000..a2dc23ea --- /dev/null +++ b/book/src/getting-started/installation.md @@ -0,0 +1,99 @@ +# Installation + +This guide will help you set up StarPerf 2.0 on your system. + +## Prerequisites + +StarPerf 2.0 requires: +- **Python 3.10** or higher +- Internet connection (for downloading TLE data and dependencies) + +### Version Comparison + +| Version | Requirements | +|---------|--------------| +| **StarPerf 1.0** | Python 2.7+, MATLAB 2013b+, STK 11+, STK Integration license | +| **StarPerf 2.0** | Python 3.10+ only | + +As you can see, StarPerf 2.0 dramatically simplifies the installation process! + +## Installation Steps + +We recommend using [uv](https://github.com/astral-sh/uv), a fast Python package and project manager, to manage dependencies and virtual environments. + +### Step 1: Install uv + +Choose the appropriate method for your operating system: + +#### MacOS/Linux + +```bash +# Method 1: Using curl +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Method 2: Using Homebrew (MacOS only) +brew install uv +``` + +#### Windows + +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" +``` + +For more installation options, refer to the [official uv documentation](https://docs.astral.sh/uv/getting-started/installation/). + +### Step 2: Clone the Repository + +```bash +git clone https://github.com/SpaceNetLab/StarPerf_Simulator.git +cd StarPerf_Simulator +``` + +### Step 3: Install Dependencies + +Once you have cloned the repository and installed uv, install all required dependencies: + +```bash +uv sync +``` + +This command will: + +- Automatically create a virtual environment +- Install all necessary Python libraries +- Set up your development environment + +## Required Python Libraries + +StarPerf 2.0 depends on the following third-party libraries: + +| Library | Version | Purpose | +|---------|---------|---------| +| h3 | 4.0.0b2 | Geospatial indexing | +| h5py | 3.10.0 | HDF5 file handling | +| numpy | 1.24.4 | Numerical computing | +| openpyxl | 3.1.2 | Excel file processing | +| importlib-metadata | 6.8.0 | Package metadata | +| skyfield | 1.46 | Satellite position calculation | +| sgp4 | 2.22 | Orbital propagation | +| pandas | 2.1.0 | Data manipulation | +| poliastro | 0.17.0 | Astrodynamics | +| astropy | 5.3.3 | Astronomy computations | +| networkx | 3.1 | Graph algorithms | +| requests | 2.31.0 | HTTP library | +| jenkspy | 0.4.0 | Natural breaks algorithm | +| pyecharts | 2.0.4 | Visualization | +| global_land_mask | 1.0.0 | Land/ocean detection | + +These are automatically installed when running `uv sync`. + +## Verify Installation + +To verify that StarPerf is installed correctly, run: + +```bash +uv run python StarPerf.py +``` + +If everything is set up correctly, you should see the simulation start smoothly. diff --git a/book/src/getting-started/overview.md b/book/src/getting-started/overview.md new file mode 100644 index 00000000..43b09423 --- /dev/null +++ b/book/src/getting-started/overview.md @@ -0,0 +1,79 @@ +# Overview + +StarPerf is a comprehensive platform designed to simulate and analyze the network performance of mega-constellation satellite networks such as Starlink and OneWeb. + +## What's New in StarPerf 2.0 + +StarPerf 2.0 represents a major upgrade from version 1.0 with significant improvements: + +### Key Improvements + +- **No External Dependencies**: + - Fully implemented in Python, no longer requires STK, MATLAB, or other third-party orbit analysis tools +- **Modern Python**: + - Built on Python 3.10+ with modern libraries +- **Framework + Plugin Architecture**: + - Highly extensible and modular design allowing easy customization +- **Enhanced Functionality**: + - Richer features including traffic plugins, energy consumption simulation, and attack modeling + +### Architecture Philosophy + +The platform follows a **"framework + plugin"** architecture: + +- **Framework**: Provides the core functionality and unified programming interfaces (APIs) +- **Plugins**: Implement specific features (beam placement, routing strategies, damage models, etc.) +- **Decoupled Design**: Plugins and framework are independent, enabling high extensibility + +## Constellation Configuration Methods + +Pre-configured examples include: + +- **Starlink**: SpaceX's mega-constellation +- **OneWeb**: Low-earth orbit communications constellation +- **Telesat**: LEO satellite constellation +- **Boeing**: Custom constellation configurations + +StarPerf 2.0 supports two ways to build constellations: + +### 1. XML-based Configuration + +Build theoretical Walker-Ξ΄ constellations using XML configuration files. This method is ideal for: + +- Exploring constellation design parameters +- Studying hypothetical configurations +- Quick prototyping + +### 2. TLE-based Configuration + +Build real constellations using Two-Line Element (TLE) data. This method is perfect for: + +- Analyzing existing constellations (Starlink, OneWeb, etc.) +- Working with real orbital data +- Comparing simulation with reality + +## Core Capabilities + +### Performance Simulation + +- Area-to-area network performance profiling +- High mobility impact analysis +- Multi-timeslot evaluation + +### Constellation Scaling + +- Adjust number of satellites +- Modify link availability and capacity +- Explore multiple operating conditions + +### Visualization + +- 3D interactive constellation rendering using Cesium +- Satellite trajectory visualization +- Ground station coverage display + +### Security Simulation + +- Attack modeling (link flooding, energy drain, etc.) +- Traffic generation and analysis +- Energy consumption profiling diff --git a/book/src/getting-started/quick-start.md b/book/src/getting-started/quick-start.md new file mode 100644 index 00000000..8173dc1d --- /dev/null +++ b/book/src/getting-started/quick-start.md @@ -0,0 +1,141 @@ +# Quick Start + +This guide will help you run your first StarPerf simulation in just a few minutes. + +## Running the Example Simulation + +The easiest way to get started is to run the provided example: + +```bash +uv run python StarPerf.py +``` + +This command will execute a default simulation configured in `StarPerf.py`. + +## Understanding StarPerf.py + +The `StarPerf.py` file serves as the entry point for simulations. It typically includes: + +1. **Configuration**: Set simulation parameters +2. **Constellation Generation**: Create or load constellation data +3. **Performance Evaluation**: Run analysis on the constellation +4. **Results Output**: Save and visualize results + +## Your First Custom Simulation + +Let's create a simple custom simulation script. Create a new file called `my_simulation.py`: + +```python +# Import required modules +from src.constellation_generation.by_XML import constellation_configuration + +# Define simulation parameters +dT = 5730 # Timestamp interval in seconds +constellation_name = "Starlink" # Name of constellation + +# Generate constellation +print("Generating constellation...") +constellation = constellation_configuration.constellation_configuration( + dT=dT, + constellation_name=constellation_name +) + +# Print basic information +print(f"\nConstellation: {constellation_name}") +print(f"Number of shells: {len(constellation.shells)}") +print(f"Total satellites: {sum(len(shell.satellites) for shell in constellation.shells)}") +print("\nSimulation complete!") +``` + +Run your simulation: + +```bash +uv run python my_simulation.py +``` + +### Step-by-Step Breakdown + +(1) Define Parameters + +```python +dT = 5730 # How often to record timestamps +constellation_name = "Starlink" +h3_resolution = 2 # Geospatial resolution +minimum_elevation = 25 # Minimum elevation angle (degrees) +``` + +(2) Generate Constellation + +Choose between XML or TLE-based generation: + +**XML-based (theoretical constellation):** + +```python +from src.constellation_generation.by_XML import constellation_configuration + +constellation = constellation_configuration.constellation_configuration( + dT=dT, + constellation_name=constellation_name +) +``` + +**TLE-based (real constellation):** + +```python +from src.constellation_generation.by_TLE import constellation_configuration + +constellation = constellation_configuration.constellation_configuration( + dT=dT, + constellation_name=constellation_name +) +``` + +(3) Configure Connectivity + +```python +from src.XML_constellation.constellation_connectivity import connectivity_mode_plugin_manager + +# Initialize connectivity manager +conn_manager = connectivity_mode_plugin_manager.connectivity_mode_plugin_manager() + +# Set connection mode (e.g., +Grid) +conn_manager.set_connection_mode("positive_Grid") + +# Execute connectivity policy +conn_manager.execute_connection_policy( + constellation=constellation, + dT=dT +) +``` + +(4) Evaluate Performance + +```python +from src.XML_constellation.constellation_evaluation import evaluation + +# Calculate coverage +coverage_results = evaluation.coverage( + constellation_name=constellation_name, + dT=dT, + sh=constellation.shells[0], + tile_size=10, + minimum_elevation=25 +) + +print(f"Average coverage: {sum(coverage_results)/len(coverage_results):.2f}") +``` + +## Next Steps + +Now that you've run your first simulation, explore more: + +- **[User Guide](../user-guide/introduction.md)** + - Understand the architecture in depth +- **[Core Modules](../core-modules/overview.md)** + - Learn about different functional modules +- **[Examples](../examples/overview.md)** + - Study detailed example scenarios +- **[API Reference](../api-reference/introduction.md)** + - Dive into the programming interfaces + +Happy simulating with StarPerf! \ No newline at end of file diff --git a/book/src/images/TLEconstellation_generation_test_result.png b/book/src/images/TLEconstellation_generation_test_result.png new file mode 100644 index 00000000..4748268a Binary files /dev/null and b/book/src/images/TLEconstellation_generation_test_result.png differ diff --git a/book/src/images/XMLconstellation_generation_test_result.png b/book/src/images/XMLconstellation_generation_test_result.png new file mode 100644 index 00000000..15366eae Binary files /dev/null and b/book/src/images/XMLconstellation_generation_test_result.png differ diff --git a/book/src/images/beam_random_placement_execution_result.png b/book/src/images/beam_random_placement_execution_result.png new file mode 100644 index 00000000..08a113be Binary files /dev/null and b/book/src/images/beam_random_placement_execution_result.png differ diff --git a/book/src/images/config_module_architecture.png b/book/src/images/config_module_architecture.png new file mode 100644 index 00000000..20457d96 Binary files /dev/null and b/book/src/images/config_module_architecture.png differ diff --git a/book/src/images/h5_file_introduction.png b/book/src/images/h5_file_introduction.png new file mode 100644 index 00000000..77f06b6d Binary files /dev/null and b/book/src/images/h5_file_introduction.png differ diff --git a/book/src/images/h5_file_tree_structure.png b/book/src/images/h5_file_tree_structure.png new file mode 100644 index 00000000..ee0d5af3 Binary files /dev/null and b/book/src/images/h5_file_tree_structure.png differ diff --git a/book/src/images/input_orbit_number.png b/book/src/images/input_orbit_number.png new file mode 100644 index 00000000..53310e63 Binary files /dev/null and b/book/src/images/input_orbit_number.png differ diff --git a/book/src/images/kernel_module_architecture.png b/book/src/images/kernel_module_architecture.png new file mode 100644 index 00000000..6bd014ad Binary files /dev/null and b/book/src/images/kernel_module_architecture.png differ diff --git a/book/src/images/level_1_architecture.png b/book/src/images/level_1_architecture.png new file mode 100644 index 00000000..b41f73e1 Binary files /dev/null and b/book/src/images/level_1_architecture.png differ diff --git a/book/src/images/new_kernel_arch.png b/book/src/images/new_kernel_arch.png new file mode 100644 index 00000000..019aa33e Binary files /dev/null and b/book/src/images/new_kernel_arch.png differ diff --git a/book/src/images/raan_distribution.png b/book/src/images/raan_distribution.png new file mode 100644 index 00000000..8ca19db9 Binary files /dev/null and b/book/src/images/raan_distribution.png differ diff --git a/book/src/images/satellite_visibility_time.png b/book/src/images/satellite_visibility_time.png new file mode 100644 index 00000000..2851b2df Binary files /dev/null and b/book/src/images/satellite_visibility_time.png differ diff --git a/book/src/images/satellite_visibility_time_result.png b/book/src/images/satellite_visibility_time_result.png new file mode 100644 index 00000000..b019ed9b Binary files /dev/null and b/book/src/images/satellite_visibility_time_result.png differ diff --git a/book/src/images/starperfpy_execute_information.png b/book/src/images/starperfpy_execute_information.png new file mode 100644 index 00000000..d22b61ce Binary files /dev/null and b/book/src/images/starperfpy_execute_information.png differ diff --git a/book/src/images/tle_download_success.png b/book/src/images/tle_download_success.png new file mode 100644 index 00000000..199567bb Binary files /dev/null and b/book/src/images/tle_download_success.png differ diff --git a/book/src/images/tle_tree_structure.png b/book/src/images/tle_tree_structure.png new file mode 100644 index 00000000..2295256d Binary files /dev/null and b/book/src/images/tle_tree_structure.png differ diff --git a/book/src/images/view_h3_cells_h3id.png b/book/src/images/view_h3_cells_h3id.png new file mode 100644 index 00000000..7de0c762 Binary files /dev/null and b/book/src/images/view_h3_cells_h3id.png differ diff --git a/book/src/user-guide/architecture.md b/book/src/user-guide/architecture.md new file mode 100644 index 00000000..9a667df9 --- /dev/null +++ b/book/src/user-guide/architecture.md @@ -0,0 +1,27 @@ +# Architecture + +The first-level architecture of StarPerf 2.0 is as follows: + +![StarPerf 2.0 Architecture](../images/level_1_architecture.png) + +## Module Overview + +The functions of each first-level module in the above figure are as follows: + +**Table 2: StarPerf 2.0 first-level modules and functions** + +| Module | Function | +| :---------: | :----------------------------------------------------------: | +| config/ | **Configuration Information Module**, is used to store configuration files, such as constellation configuration information, ground station information, etc. | +| data/ | **Data Storage Module**, is used to store preloaded data and intermediate data and result data generated during system operation, such as cells of different resolutions in the h3 library, satellite position data, etc. | +| docs/ | **Documentation Module**, is used to store various documentation, pictures, and dependent library information of StarPerf 2.0, such as this document, the list of third-party Python libraries that the system depends on. | +| samples/ | **Test Sample Module**, is used to store test case scripts for each functional module, and these scripts are independent of each other and can be directly called and run. | +| kits/ | **Auxiliary Script Module**, is used to store some auxiliary scripts written to complete system functions, such as ".xlsx" file conversion ".xml" file scripts, etc. | +| src/ | **Kernel Module**, is the core module of StarPerf 2.0, which contains all the core code of each functional module. The "framework + plug-in" architecture mentioned earlier is this module. | +| StarPerf.py | **StarPerf 2.0 Startup Script**, users should start StarPerf 2.0 from this script. | + +--- + +**Navigation:** +- [Previous: Environment & Dependencies](environment.md) +- [Next: Configuration](configuration.md) diff --git a/book/src/user-guide/auxiliary-scripts.md b/book/src/user-guide/auxiliary-scripts.md new file mode 100644 index 00000000..585a536f --- /dev/null +++ b/book/src/user-guide/auxiliary-scripts.md @@ -0,0 +1,37 @@ +# Auxiliary Script Module: kits/ + +This module stores some auxiliary scripts written to complete the core functions of StarPerf 2.0, such as file format conversion scripts, h5 file reading scripts, etc. + +## Viewing h5 File Tree Structure + +If you want to view the tree structure of an h5 file, you can run `get_h5file_tree_structure.py`. This script will read `data/XML_constellation/Starlink.h5` and display the group and dataset information in it. + +The script execution results are as follows: + +![h5 File Tree Structure](../images/h5_file_tree_structure.png) + +**Explanation of execution results:** The above figure shows that `data/XML_constellation/Starlink.h5` contains 2 first-level groups: position and delay, which represent satellite position data and constellation delay matrix data respectively. Each first-level group contains 4 second-level groups, which represent each layer of shell data. Each secondary group contains 2 datasets, representing the data of two timestamps. + +## Viewing h3 Cell IDs + +If you want to view the h3id of all cells at the specified resolution in `data/h3_cells_id_res0-4.h5`, you can execute `print_h3_cells_h3id.py`. + +Assume that you now want to view the h3id of all cells with a resolution of 0, part of the execution results of this script are as follows: + +![View h3 Cells h3id](../images/view_h3_cells_h3id.png) + +**Explanation of execution results:** Each row in the above figure represents the h3id of a cell with a resolution of 0. Due to space limitations, only part of the execution results are shown here. More detailed results can be viewed by executing the script. + +## Other Utility Scripts + +The `kits/` directory may contain additional utility scripts for: +- File format conversion (e.g., `.xlsx` to `.xml`) +- Data preprocessing +- Configuration validation +- Testing and debugging tools + +--- + +**Navigation:** +- [Previous: Data Storage](data-storage.md) +- [Next: Core Modules](../core-modules/README.md) diff --git a/book/src/user-guide/config/ground-stations.md b/book/src/user-guide/config/ground-stations.md new file mode 100644 index 00000000..ca8ad56a --- /dev/null +++ b/book/src/user-guide/config/ground-stations.md @@ -0,0 +1 @@ +# Ground Stations diff --git a/book/src/user-guide/config/h5-format.md b/book/src/user-guide/config/h5-format.md new file mode 100644 index 00000000..902c06e6 --- /dev/null +++ b/book/src/user-guide/config/h5-format.md @@ -0,0 +1 @@ +# H5 File Format diff --git a/book/src/user-guide/config/pops.md b/book/src/user-guide/config/pops.md new file mode 100644 index 00000000..f122b9dd --- /dev/null +++ b/book/src/user-guide/config/pops.md @@ -0,0 +1 @@ +# POPs diff --git a/book/src/user-guide/config/tle-constellation.md b/book/src/user-guide/config/tle-constellation.md new file mode 100644 index 00000000..eded683e --- /dev/null +++ b/book/src/user-guide/config/tle-constellation.md @@ -0,0 +1 @@ +# TLE Constellation diff --git a/book/src/user-guide/config/xml-constellation.md b/book/src/user-guide/config/xml-constellation.md new file mode 100644 index 00000000..f0865c7c --- /dev/null +++ b/book/src/user-guide/config/xml-constellation.md @@ -0,0 +1 @@ +# XML Constellation diff --git a/book/src/user-guide/configuration.md b/book/src/user-guide/configuration.md new file mode 100644 index 00000000..ae152575 --- /dev/null +++ b/book/src/user-guide/configuration.md @@ -0,0 +1,160 @@ +# Configuration Information Module: config/ + +This module stores all data information related to constellation configuration in StarPerf 2.0, and the structure diagram of this module is as follows: + +![Config Module Architecture](../images/config_module_architecture.png) + +## Module Overview + +The functions of each module in the above figure are as follows: + +**Table 3: config module** + +| Module | Function | +| ------------------ | ------------------------------------------------------------ | +| TLE_constellation/ | Stores the data information required to generate constellations using TLE. Each constellation is described by a TLE data file (.h5) and a launch batch information file (.xml). | +| XML_constellation/ | Stores the data information required to generate constellations using XML data. Each constellation is described by an .xml file. | +| ground_stations/ | Stores the ground station data of the constellation. All ground station information for each constellation is described by an .xml file. | +| POPs/ | Store the POP points data of the constellation. All POP points information for each constellation is described by an .xml file. | + +## h5 File Introduction + +This format file is generally used to store scientific data. It has a structure similar to a "file directory" and allows the data in the file to be organized in many different structured ways, just like working with files on a computer. + +There are two main structures in h5 files: **group** and **dataset**. An h5 file is a combination of several groups and datasets. + +- **group**: A grouping structure containing 0 or more instances of a dataset or group, along with supporting metadata. +- **dataset**: A data collection organized in an array-like manner, working like a numpy array, a dataset is a numpy.ndarray. The specific dataset can be images, tables, or even pdf files and excel. + +Working with groups and datasets is in many ways similar to working with directories and files in UNIX. Like UNIX directories and files, objects in h5 files are usually described by providing full (or absolute) pathnames. + +![h5 File Introduction](../images/h5_file_introduction.png) + +Reading and writing h5 files can be completed through Python's h5py library. For specific usage, see `kits/`. + +## TLE_constellation/ + +This folder stores the data information of the constellation generated by TLE. Each constellation is described by a folder named after the constellation. There are two files in this folder, one is the .h5 file that stores TLE, and the other is the .xml file that stores satellite launch information. + +In the .h5 file that stores TLE, each day's TLE data is a Group, and the Group name is the date of the day. Each Group contains two Datasets. The first Dataset is a TLE containing two rows of information, and the second Dataset is a TLE in JSON format. + +For example, the tree structure of the `config/TLE_constellation/Starlink/tle.h5` file is as shown below: + +![TLE Tree Structure](../images/tle_tree_structure.png) + +### Launch Information XML Structure + +The structure of the .xml file that stores satellite launch information is as follows: + +```xml + + + 2019-074 + 550 + 53 + + ...... + +``` + +The root element of the xml file is "Launches". The root element contains several elements, each element is named with "Launch+\" (such as "Launch1", "Launch2", etc.), which is used to represent a satellite launch information. + +Each launch contains three types of information: +- [COSPAR_ID](https://en.wikipedia.org/wiki/International_Designator#:~:text=The%20International%20Designator%2C%20also%20known%20as%20COSPAR%20ID%2C,sequential%20identifier%20of%20a%20piece%20in%20a%20launch.) +- Orbit altitude Altitude (unit: kilometers) +- Orbit inclination (unit: Β°) + +## XML_constellation/ + +This folder stores the data information of the constellation generated by XML. Walker-Ξ΄ constellations and polar constellations can be generated using XML files. In this way of generating constellations, each constellation only requires a .xml configuration information file, and no TLE is required. + +Taking Starlink as an example, the .xml configuration information file of the constellation is `config/XML_constellation/Starlink.xml`. The content of the file is as follows: + +```xml + + 4 + + 550 + 5731 + 53.0 + 1 + 72 + 22 + + ...... + +``` + +The root element of the document is ``. The first sub-element inside the root element is ``, which represents the number of shells in the constellation. + +In this example, we assume that the value is 4, then there will be 4 sub-elements under the root element `` ``...``, representing different shells respectively. + +There are 6 sub-elements inside each shell, representing: +- Orbital altitude (unit: km) +- Orbital period (unit: s) +- Orbital inclination (unit: Β°) +- Phase shift +- Number of orbits +- Number of satellites in each orbit + +## ground_stations/ + +This folder stores the ground station information of the constellation. The ground station information of each constellation is described by an .xml file named after the constellation name. + +The content of Starlink's ground station information file `config/ground_stations/Starlink.xml` is as follows: + +```xml + + + -12.74832 + -38.28305 + CamaΓ§ari, BR + Ka + 8 + 2.1 + 1.3 + + ...... + +``` + +The root element of the document is ``. In this example, we assume that there are 10 ground stations, then there will be 10 sub-elements under the root element `` ``...``, representing different ground stations respectively. + +There are 7 sub-elements inside each GS, representing: +- Ground station latitude +- Ground station longitude +- Ground station location description +- Ground station frequency +- Ground station antenna count +- Ground station uplink (GHz) +- Ground station downlink (GHz) + +## POPs/ + +This folder stores the POP information of the constellation. The POP information of each constellation is described by an .xml file named after the constellation name. + +The content of Starlink's POP information file `config/POPs/Starlink.xml` is as follows: + +```xml + + + 47.6048790423666 + -122.333542912036 + SEA - STTLWAX1 + + ...... + +``` + +The root element of the document is ``. In this example, we assume that there are 10 POPs, then there will be 10 sub-elements under the root element `` ``...``, representing different POPs respectively. + +There are 3 sub-elements inside each POP, representing: +- POP latitude +- POP longitude +- POP name + +--- + +**Navigation:** +- [Previous: Architecture](architecture.md) +- [Next: Data Storage](data-storage.md) diff --git a/book/src/user-guide/data-storage.md b/book/src/user-guide/data-storage.md new file mode 100644 index 00000000..f6236038 --- /dev/null +++ b/book/src/user-guide/data-storage.md @@ -0,0 +1,32 @@ +# Data Storage Module: data/ + +This module stores various data when StarPerf 2.0 is running, which can be divided into three categories: + +## Preloaded Data + +The data that StarPerf 2.0 must read when running certain functions, such as the data of Uber h3 library cells, which is located in `data/h3_cells_id_res0-4.h5`. + +## Intermediate Data + +StarPerf 2.0 needs to temporarily store some data when running certain functions, such as: +- The delay matrix of the constellation +- Satellite position data +- Other temporary computation results + +These data are stored in: +- `data/TLE_constellation/.h5` (such as `data/TLE_constellation/Starlink.h5`) +- `data/XML_constellation/.h5` (such as `data/XML_constellation/Starlink.h5`) + +## Result Data + +The final results produced after StarPerf 2.0 runs, such as: +- Output drawings in PDF format +- Analysis reports +- Performance metrics +- Other simulation results + +--- + +**Navigation:** +- [Previous: Configuration](configuration.md) +- [Next: Auxiliary Scripts](auxiliary-scripts.md) diff --git a/book/src/user-guide/environment.md b/book/src/user-guide/environment.md new file mode 100644 index 00000000..41d09b4b --- /dev/null +++ b/book/src/user-guide/environment.md @@ -0,0 +1,51 @@ +# Environment & Dependencies + +Before we begin, we first introduce the operating environment of StarPerf 2.0 and its dependent libraries so that you can install StarPerf 2.0 correctly. + +## Python Version + +StarPerf 2.0 is developed based on Python 3.10, so we recommend that your **Python version is 3.10**. + +## Third-Party Libraries + +In addition to the Python 3.10 standard library, StarPerf 2.0 uses the following open source Python third-party libraries: + +**Table 1: Third-party Python libraries and versions** + +| Library | Version | +| :----------------: |:-------:| +| h3 | 4.0.0b2 | +| h5py | 3.10.0 | +| numpy | 1.24.4 | +| openpyxl | 3.1.2 | +| importlib-metadata | 6.8.0 | +| skyfield | 1.46 | +| sgp4 | 2.22 | +| pandas | 2.1.0 | +| poliastro | 0.17.0 | +| astropy | 5.3.3 | +| networkx | 3.1 | +| requests | 2.31.0 | +| jenkspy | 0.4.0 | +| pyecharts | 2.0.4 | +| global_land_mask | 1.0.0 | + +## Installation + +The third-party Python libraries in the above table and their corresponding version numbers are all listed in `docs/third-party_libraries_list.txt` in the form of `LibraryName==LibraryVersion` (such as `numpy==1.24.4`). + +You can execute the following command in the root directory of the StarPerf 2.0 project to install all third-party Python libraries at once: + +```bash +pip install -r docs/third-party_libraries_list.txt +``` + +## System Dependencies + +Finally, StarPerf 2.0 does not depend on any non-Python environment, so you do not need to install any third-party orbit analysis/calculation tools (STK, etc.). + +--- + +**Navigation:** +- [Previous: Introduction](introduction.md) +- [Next: Architecture](architecture.md) diff --git a/book/src/user-guide/introduction.md b/book/src/user-guide/introduction.md new file mode 100644 index 00000000..c1795904 --- /dev/null +++ b/book/src/user-guide/introduction.md @@ -0,0 +1,113 @@ +# Introduction + +StarPerf 2.0 is a feature-rich, highly open, and easily extensible constellation performance simulation platform. + +## Architecture Philosophy + +The platform architecture follows a: + +**"Framework + Plugin"** model + +- **Framework**: Implements various underlying functions and provides unified programming interface APIs +- **Plugins**: Implement specific features based on the framework's APIs +- **Decoupled Design**: Plugins and framework are independent, enabling high openness and easy extensibility + +## Constellation Building Methods + +StarPerf 2.0 supports two methods to build constellations: + +### 1. XML Configuration Files +Build **Walker-Ξ΄** constellations using XML configuration files. This method is ideal for: +- Designing theoretical constellations +- Exploring different constellation parameters +- Quick prototyping and testing + +### 2. TLE Data +Build **real constellations** (like Starlink) using Two-Line Element (TLE) data. This approach allows: +- Analysis of existing mega-constellations +- Working with actual orbital parameters +- Validation against real-world data + +## Available Plugins + +StarPerf 2.0 comes with various functional plugins out of the box: + +| Plugin Category | Examples | +|----------------|----------| +| **Connectivity** | +Grid connectivity mode | +| **Routing** | Shortest Path Routing | +| **Survivability** | Solar Storm Damage Model | +| **Beam Placement** | Random Placement Algorithm | +| **Traffic** | Traffic generation patterns | +| **Attack Simulation** | Link flooding, Energy drain attacks | + +## Custom Plugin Development + +You can write your own functional plugins based on the interface APIs provided by the framework to achieve personalized functionality. Each plugin category has well-defined specifications: + +- Clear interface requirements +- Standardized parameter lists +- Defined return value formats +- Storage conventions for intermediate data + +## Document Structure + +This documentation is organized to help you understand and use StarPerf 2.0 effectively: + +1. **Environment & Dependencies** - Set up your development environment +2. **Architecture** - Understand the system design +3. **Configuration Module** - Learn how to configure constellations +4. **Data Storage** - Understand data organization +5. **Core Modules** - Explore functional capabilities +6. **API Reference** - Detailed interface specifications + +## Key Concepts + +Before diving deeper, familiarize yourself with these key concepts: + +### Constellation +A complete satellite network consisting of one or more shells. + +### Shell +A layer in the constellation with satellites at the same orbital altitude and inclination. + +### Orbit +A circular path around Earth containing multiple satellites. + +### Satellite +Individual spacecraft in the constellation, equipped with antennas and communication capabilities. + +### ISL (Inter-Satellite Link) +Communication links between satellites, enabling direct satellite-to-satellite communication. + +### Ground Station (GS) +Ground infrastructure that communicates with satellites, serving as entry/exit points for terrestrial networks. + +### POP (Point of Presence) +Network access points where satellite traffic connects to terrestrial infrastructure. + +### Timeslot +Discrete time intervals at which constellation state is recorded and analyzed. + +### H3 Resolution +Hierarchical geospatial indexing system used to divide Earth's surface into hexagonal cells. + +## Getting Help + +Throughout this documentation, you'll find: +- πŸ“˜ **Notes**: Important information to keep in mind +- ⚠️ **Warnings**: Critical considerations +- πŸ’‘ **Tips**: Helpful suggestions +- πŸ“ **Examples**: Code samples and use cases + +If you need assistance: +- Review the [API Reference](../api-reference/introduction.md) +- Check [Examples](../examples/overview.md) +- Contact the development team (see [Contact](../about/contact.md)) + +## Next Steps + +Continue reading to understand: +- [Environment & Dependencies](./environment.md) - Required libraries and versions +- [Architecture](./architecture.md) - System organization and modules +- [Configuration Module](./configuration.md) - How to configure constellations diff --git a/book/src/visualization/constellation.md b/book/src/visualization/constellation.md new file mode 100644 index 00000000..ec75e4d8 --- /dev/null +++ b/book/src/visualization/constellation.md @@ -0,0 +1,266 @@ +# Constellation Visualization + +StarPerf extends the visualization of mainstream LEO constellations based on Cesium, providing a highly interactive and realistic 3D environment for viewing satellite networks. + +## Overview + +The visualization module allows you to: +- View constellation topology in 3D +- Track satellite movements in real-time +- Visualize ground station coverage +- Display inter-satellite links (ISLs) +- Analyze spatial distribution of satellites + +## Prerequisites + +Before using the visualization features, you need: + +1. **Cesium Token**: Obtain your personal Cesium Ion token from the [official Cesium website](https://cesium.com/ion/) +2. **Node.js**: Version 13 or newer +3. **http-server**: Install via npm + +## Setup Instructions + +### Step 1: Configure Cesium Token + +Set your Cesium token in the visualization configuration file: + +```bash +# Edit the head.html file +vi ./visualization/html_head_tail/head.html +``` + +Assign your token to the `Cesium.Ion.defaultAccessToken` parameter: + +```javascript +Cesium.Ion.defaultAccessToken = 'YOUR_TOKEN_HERE'; +``` + +### Step 2: Install Node.js and http-server + +**macOS/Linux:** +```bash +# Install Node.js (if not already installed) +# Using Homebrew on macOS: +brew install node + +# Or download from nodejs.org + +# Install http-server globally +npm install -g http-server +``` + +**Windows:** +```powershell +# Download and install Node.js from nodejs.org +# Then install http-server: +npm install -g http-server +``` + +> **Note**: It is recommended to use Node.js version 13 or newer. Older versions may encounter issues when installing http-server. + +### Step 3: Generate Visualization + +In your simulation script, uncomment and run the constellation visualization section: + +```python +# In StarPerf.py, uncomment the visualization section +from visualization import constellation_visualization + +# Generate visualization for your constellation +constellation_visualization.visualize_constellation( + constellation=my_constellation, + output_dir="./visualization/CesiumAPP" +) +``` + +Run the script: +```bash +uv run python StarPerf.py +``` + +This will generate an HTML file in the `./visualization/CesiumAPP` directory. + +### Step 4: Start Local Server + +Navigate to the CesiumAPP directory and start the server: + +```bash +cd ./visualization/CesiumAPP +http-server -p 8081 +``` + +You should see output similar to: +``` +Starting up http-server, serving ./ +Available on: + http://127.0.0.1:8081 + http://192.168.1.100:8081 +Hit CTRL-C to stop the server +``` + +### Step 5: View in Browser + +Open your web browser and navigate to: + +``` +http://127.0.0.1:8081/ +``` + +Replace `` with the name of the HTML file generated by the visualization code (e.g., `starlink_visualization.html`). + +## Visualization Features + +### Interactive 3D Globe + +The Cesium-based visualization provides: + +- **Pan**: Click and drag to rotate the globe +- **Zoom**: Scroll to zoom in/out +- **Tilt**: Right-click and drag to change viewing angle +- **Reset**: Double-click to reset view + +### Satellite Tracking + +- Click on any satellite to view its details +- Track satellite trajectory over time +- View orbital parameters +- Display satellite ID and shell information + +### Ground Station Coverage + +- Visualize coverage areas for ground stations +- Show active communication links +- Display elevation angles and signal strength + +### Time Animation + +- Play/pause satellite motion +- Adjust animation speed +- Jump to specific timestamps +- View constellation state at different times + +## Example Visualizations + +### Starlink Constellation + +```python +from visualization import constellation_visualization +from src.constellation_generation.by_TLE import constellation_configuration + +# Generate Starlink constellation +constellation = constellation_configuration.constellation_configuration( + dT=1000, + constellation_name="Starlink" +) + +# Create visualization +constellation_visualization.visualize_constellation( + constellation=constellation, + output_dir="./visualization/CesiumAPP", + filename="starlink_viz.html" +) +``` + +### OneWeb Constellation + +```python +# Visualize OneWeb constellation +constellation = constellation_configuration.constellation_configuration( + dT=1000, + constellation_name="OneWeb" +) + +constellation_visualization.visualize_constellation( + constellation=constellation, + output_dir="./visualization/CesiumAPP", + filename="oneweb_viz.html" +) +``` + +## Customization Options + +You can customize visualization parameters: + +```python +constellation_visualization.visualize_constellation( + constellation=constellation, + output_dir="./visualization/CesiumAPP", + filename="my_visualization.html", + show_orbits=True, # Display orbital paths + show_isls=True, # Show inter-satellite links + show_ground_stations=True, # Display ground stations + satellite_color="cyan", # Satellite marker color + orbit_color="white", # Orbital path color + animation_speed=1.0 # Animation speed multiplier +) +``` + +## Sample Visualizations + +Pre-configured visualization samples are available in: + +``` +visualization/samples/ +β”œβ”€β”€ Starlink.py # Starlink visualization +β”œβ”€β”€ OneWeb.py # OneWeb visualization +β”œβ”€β”€ Telesat.py # Telesat visualization +β”œβ”€β”€ Boeing.py # Boeing constellation +└── visualization_test_cases.py # Test various configurations +``` + +Run a sample: +```bash +uv run python visualization/samples/Starlink.py +``` + +## Troubleshooting + +### Common Issues + +**1. Cesium Token Error** +``` +Error: Cesium ion access token is invalid +``` +**Solution**: Verify your token is correctly set in `head.html` + +**2. http-server Not Found** +``` +command not found: http-server +``` +**Solution**: Install http-server globally: `npm install -g http-server` + +**3. Port Already in Use** +``` +Error: Port 8081 is already in use +``` +**Solution**: Use a different port: `http-server -p 8082` + +**4. Blank Page/No Satellites Visible** +- Check browser console for JavaScript errors +- Verify the HTML file was generated correctly +- Ensure constellation data was loaded successfully + +### Browser Compatibility + +Recommended browsers: +- Chrome/Chromium (recommended) +- Firefox +- Safari +- Edge + +> **Note**: WebGL support is required. Enable hardware acceleration in your browser settings for best performance. + +## Performance Considerations + +For large constellations (10,000+ satellites): +- Visualization may be slow on older hardware +- Consider visualizing one shell at a time +- Reduce animation speed for smoother playback +- Use a more powerful GPU if available + +## Next Steps + +- Explore [Examples](../examples/overview.md) for complete visualization workflows +- Learn about [Constellation Generation](../core-modules/constellation-generation/overview.md) +- Check out [Performance Evaluation](../core-modules/evaluation/overview.md) to analyze your visualized constellations diff --git a/book/src/visualization/setup.md b/book/src/visualization/setup.md new file mode 100644 index 00000000..7510957f --- /dev/null +++ b/book/src/visualization/setup.md @@ -0,0 +1,280 @@ +# Visualization Setup + +This page provides detailed setup instructions for StarPerf's visualization capabilities. + +## Quick Setup + +For a quick start with visualization: + +```bash +# 1. Install Node.js and http-server +npm install -g http-server + +# 2. Configure your Cesium token in visualization/html_head_tail/head.html + +# 3. Generate visualization in your script +uv run python StarPerf.py # With visualization code uncommented + +# 4. Start the server +cd visualization/CesiumAPP +http-server -p 8081 + +# 5. Open browser to http://127.0.0.1:8081/.html +``` + +## Detailed Configuration + +### Cesium Ion Access Token + +1. Visit [Cesium Ion](https://cesium.com/ion/) +2. Create a free account or sign in +3. Navigate to "Access Tokens" in your dashboard +4. Copy your default token or create a new one +5. Paste it in `visualization/html_head_tail/head.html`: + +```javascript +// In head.html +Cesium.Ion.defaultAccessToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; +``` + +### Directory Structure + +The visualization module uses the following structure: + +``` +visualization/ +β”œβ”€β”€ constellation_visualization.py # Main visualization module +β”œβ”€β”€ CesiumAPP/ # Generated HTML files +β”‚ └── [generated_files].html +β”œβ”€β”€ html_head_tail/ # HTML templates +β”‚ β”œβ”€β”€ head.html # Header with Cesium config +β”‚ └── tail.html # Footer template +└── samples/ # Example scripts + β”œβ”€β”€ Starlink.py + β”œβ”€β”€ OneWeb.py + β”œβ”€β”€ Telesat.py + β”œβ”€β”€ Boeing.py + └── visualization_test_cases.py +``` + +### Node.js Version Management + +If you have multiple Node.js versions, use nvm (Node Version Manager): + +```bash +# Install nvm +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash + +# Install Node.js 18 +nvm install 18 +nvm use 18 + +# Install http-server +npm install -g http-server +``` + +## Advanced Configuration + +### Custom HTML Templates + +You can customize the visualization appearance by modifying the templates: + +**head.html** - Controls: +- Cesium library imports +- Initial camera position +- Globe appearance +- Lighting settings + +**tail.html** - Controls: +- UI controls +- Animation controls +- Information panels + +### Server Configuration + +#### Custom Port + +```bash +http-server -p 3000 +``` + +#### Enable CORS + +```bash +http-server --cors +``` + +#### Cache Control + +```bash +http-server -c-1 # Disable caching +``` + +#### Bind to All Interfaces + +```bash +http-server -a 0.0.0.0 -p 8081 +``` + +This allows access from other devices on your network at: +``` +http://:8081/.html +``` + +### Production Deployment + +For production deployment, consider using: + +**Nginx Configuration:** +```nginx +server { + listen 80; + server_name your-domain.com; + root /path/to/StarPerf_Simulator/visualization/CesiumAPP; + + location / { + try_files $uri $uri/ =404; + } +} +``` + +**Apache Configuration:** +```apache + + ServerName your-domain.com + DocumentRoot /path/to/StarPerf_Simulator/visualization/CesiumAPP + + + Options Indexes FollowSymLinks + AllowOverride None + Require all granted + + +``` + +## Visualization API + +### Basic Usage + +```python +from visualization import constellation_visualization + +# Generate visualization +constellation_visualization.visualize_constellation( + constellation=my_constellation, + output_dir="./visualization/CesiumAPP", + filename="my_viz.html" +) +``` + +### Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `constellation` | Constellation | Required | Constellation object to visualize | +| `output_dir` | str | `"./visualization/CesiumAPP"` | Output directory for HTML | +| `filename` | str | `"visualization.html"` | Output filename | +| `show_orbits` | bool | `True` | Display orbital paths | +| `show_isls` | bool | `False` | Show inter-satellite links | +| `show_ground_stations` | bool | `True` | Display ground stations | +| `satellite_color` | str | `"cyan"` | Satellite marker color | +| `orbit_color` | str | `"white"` | Orbital path color | +| `animation_speed` | float | `1.0` | Animation speed multiplier | +| `start_time` | str | `None` | Start time (ISO 8601 format) | +| `duration` | int | `None` | Duration in seconds | + +### Example with All Parameters + +```python +constellation_visualization.visualize_constellation( + constellation=starlink_constellation, + output_dir="./visualization/CesiumAPP", + filename="starlink_full.html", + show_orbits=True, + show_isls=True, + show_ground_stations=True, + satellite_color="yellow", + orbit_color="rgba(255,255,255,0.3)", + animation_speed=2.0, + start_time="2024-01-01T00:00:00Z", + duration=86400 # 24 hours +) +``` + +## Troubleshooting Guide + +### Issue: Blank Page + +**Symptoms**: Browser shows blank page with no errors + +**Solutions**: +1. Check browser console (F12) for JavaScript errors +2. Verify Cesium token is valid +3. Ensure HTML file was generated correctly +4. Check if WebGL is enabled in browser + +### Issue: Slow Performance + +**Symptoms**: Laggy visualization, low frame rate + +**Solutions**: +1. Reduce number of visible satellites (filter by shell) +2. Disable ISL visualization if not needed +3. Lower animation speed +4. Enable hardware acceleration in browser +5. Use a more powerful GPU + +### Issue: Satellites Not Appearing + +**Symptoms**: Globe loads but no satellites visible + +**Solutions**: +1. Check that constellation data was loaded successfully +2. Verify satellite positions are being generated +3. Zoom out to ensure satellites are in view +4. Check JavaScript console for errors + +### Issue: Server Won't Start + +**Symptoms**: `http-server` command fails or port in use + +**Solutions**: +```bash +# Check if port is in use +lsof -i :8081 + +# Kill process using port +kill -9 + +# Or use different port +http-server -p 8082 +``` + +## Tips and Best Practices + +### Performance Optimization + +1. **Limit Visible Satellites**: Visualize one shell at a time for large constellations +2. **Reduce Animation Speed**: Lower speeds reduce computational load +3. **Disable Unnecessary Features**: Turn off ISLs if not analyzing connectivity +4. **Use Modern Browser**: Chrome/Chromium typically has best performance + +### Visual Quality + +1. **Camera Position**: Start with a good initial camera angle +2. **Color Scheme**: Use contrasting colors for different elements +3. **Lighting**: Adjust ambient and directional lighting for clarity +4. **Orbit Trails**: Show orbit trails to visualize satellite paths + +### Workflow Integration + +1. **Generate During Simulation**: Create visualization as part of your analysis pipeline +2. **Version Control**: Save visualizations with meaningful filenames +3. **Documentation**: Include screenshots in reports +4. **Sharing**: Deploy to web server for team collaboration + +## Next Steps + +- Return to [Constellation Visualization](./constellation.md) for usage examples +- Explore [Examples](../examples/overview.md) for complete workflows +- Learn about [Constellation Generation](../core-modules/constellation-generation/overview.md) diff --git a/book/theme/css/custom.css b/book/theme/css/custom.css new file mode 100644 index 00000000..afecd509 --- /dev/null +++ b/book/theme/css/custom.css @@ -0,0 +1,120 @@ +/* Custom CSS for StarPerf Documentation */ + +/* Improve code block styling */ +pre { + border-radius: 6px; + border: 1px solid var(--sidebar-bg); +} + +/* Better table styling */ +table { + width: 100%; + border-collapse: collapse; + margin: 1em 0; +} + +table thead { + background-color: var(--table-header-bg); +} + +table th, +table td { + padding: 0.75em; + border: 1px solid var(--table-border-color); +} + +table tr:nth-child(even) { + background-color: var(--table-alternate-bg); +} + +/* Admonition blocks */ +.warning, +.note, +.tip { + padding: 1em; + margin: 1em 0; + border-left: 4px solid; + border-radius: 4px; +} + +.warning { + background-color: #fff3cd; + border-color: #ffc107; +} + +.note { + background-color: #d1ecf1; + border-color: #17a2b8; +} + +.tip { + background-color: #d4edda; + border-color: #28a745; +} + +/* Better link styling */ +a { + text-decoration: none; + color: var(--links); + transition: color 0.2s; +} + +a:hover { + text-decoration: underline; + color: var(--links-hover); +} + +/* Improve navigation */ +.nav-chapters { + font-size: 1.1em; +} + +/* Better heading anchors */ +.header a.header { + text-decoration: none; + color: inherit; +} + +.header:hover a.header { + color: var(--links); +} + +/* Code inline styling */ +code { + background-color: var(--inline-code-bg); + padding: 0.2em 0.4em; + border-radius: 3px; + font-size: 0.9em; +} + +/* Improve search box */ +#searchbar { + width: 100%; + margin: 0.5em 0; +} + +/* Better mobile responsiveness */ +@media (max-width: 768px) { + table { + font-size: 0.9em; + } + + .content { + padding: 1em; + } +} + +/* Print styles */ +@media print { + .nav-chapters { + display: none; + } + + .sidebar { + display: none; + } + + .content { + margin-left: 0; + } +}