Skip to content

Commit c9259bf

Browse files
ryanmccann1024ryanmccann1024
committed
docs: polish documentation and remove emojis
Remove emojis from all top-level markdown files for professional presentation while maintaining readability and structure. Documentation improvements: - Remove emojis from README.md and DEVELOPMENT_QUICKSTART.md - Add comprehensive CLAUDE.md with project context for AI assistants - Fix placeholder email in CODE_OF_CONDUCT.md enforcement section - Streamline CONTRIBUTING.md with references to detailed standards - Remove research planning files (new-paper-*.md) Code quality improvements: - Remove redundant default values in network_analysis.py - Fix docstring formatting in cli_to_config.py - Add ML support TODO item in core/TODO.md - Remove verbose seeding comment block in simulation.py
1 parent 94c1e44 commit c9259bf

11 files changed

Lines changed: 266 additions & 600 deletions

‎CLAUDE.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# FUSION Project Context for AI Assistants
2+
3+
This document provides context for AI assistants (like Claude) working with the FUSION codebase.
4+
5+
## Project Overview
6+
7+
FUSION (Flexible Unified System for Intelligent Optical Networking) is an open-source simulation framework for Software Defined Elastic Optical Networks (SD-EONs) with extensions for AI/ML integration, particularly reinforcement learning for network optimization and survivability.
8+
9+
## Key Architectural Concepts
10+
11+
### Core Simulation Components
12+
- **Discrete Event Simulation**: Event-driven network request processing
13+
- **RSA (Routing and Spectrum Assignment)**: The fundamental resource allocation problem
14+
- **Network Topology**: Graph-based representation using NetworkX
15+
- **Spectrum Management**: Flexible grid optical spectrum allocation
16+
- **Traffic Generation**: Poisson arrival process with configurable parameters
17+
18+
### Reinforcement Learning Integration
19+
- **Offline RL**: Training from heuristic behavior logs (BC, IQL, CQL)
20+
- **Online RL**: Integration with Stable-Baselines3 (PPO, A2C, DQN)
21+
- **Action Masking**: Safety mechanism to prevent invalid actions
22+
- **Policy Evaluation**: Baseline comparison and metrics collection
23+
24+
### Survivability Features
25+
- **Failure Types**: Link (F1), Node (F2), SRLG (F3), Geographic (F4)
26+
- **Protection Mechanisms**: 1+1 disjoint path protection
27+
- **Recovery Metrics**: Blocking probability, recovery time, fragmentation
28+
29+
## Code Organization Philosophy
30+
31+
### Module Structure
32+
- Each module contains its own `tests/` subdirectory
33+
- Every module and test directory must have a `README.md`
34+
- Use `__init__.py` to define public APIs with `__all__`
35+
- Registry pattern for pluggable algorithms
36+
37+
### Naming Conventions
38+
- **Standardized names**: `engine_props`, `sim_params`, `network_topology`
39+
- **No type suffixes**: Use type hints instead of `_dict`, `_list` suffixes
40+
- **Functions**: Verb phrases in `snake_case`
41+
- **Classes**: `PascalCase`
42+
43+
### State Management
44+
- Use `StateWrapper` for mutable configuration objects like `engine_props`
45+
- Never hardcode paths - use `pathlib.Path` and configuration
46+
- All RNG operations must be seeded for reproducibility
47+
48+
## Development Workflow
49+
50+
### Quality Tools
51+
- **ruff**: Modern linting and formatting (replaces black, flake8, isort)
52+
- **mypy**: Type checking with strict configuration
53+
- **pytest**: Unit testing with coverage reporting
54+
- **pre-commit**: Automated quality checks on commit
55+
56+
### Key Commands
57+
```bash
58+
make format # Auto-format code
59+
make lint-new # Check for issues
60+
make test-new # Run tests with coverage
61+
make check-all # Full quality check
62+
```
63+
64+
## Important Constraints and Guidelines
65+
66+
### What to Avoid
67+
- No emojis in documentation or code (per user preference)
68+
- No print statements - use logging
69+
- No hardcoded paths - use configuration
70+
- No broad exception catching
71+
- No `fusion/gui` module changes (deprecated, requires revamp)
72+
73+
### What to Follow
74+
- All functions require type annotations
75+
- All code must pass ruff and mypy checks
76+
- Functions should be under 50 lines
77+
- Files should be under 500 lines
78+
- Test coverage targets: 80-90% for most modules
79+
- Use Sphinx-style docstrings
80+
81+
## Configuration System
82+
83+
FUSION uses INI-based configuration with:
84+
- Template system in `fusion/configs/templates/`
85+
- CLI argument integration via `fusion/cli/run_sim.py`
86+
- Validation and type checking
87+
- Environment-specific overrides
88+
89+
## Testing Standards
90+
91+
### Unit Testing
92+
- Tests located in `tests/` subdirectory within each module
93+
- One test file per module: `test_<module_name>.py`
94+
- Mock all external dependencies
95+
- Follow AAA pattern (Arrange, Act, Assert)
96+
- Test naming: `test_<what>_<when>_<expected>`
97+
98+
### Integration Testing
99+
- Located in top-level `tests/` directory
100+
- Test component interactions
101+
- May use real dependencies where appropriate
102+
103+
## Common Patterns
104+
105+
### Factory Pattern
106+
See `fusion/interfaces/factory.py` for algorithm instantiation
107+
108+
### Interface/Abstract Base Classes
109+
- `AbstractRoutingAlgorithm`
110+
- `AbstractSpectrumAssigner`
111+
- `AbstractSNRMeasurer`
112+
113+
### Registry Pattern
114+
- Algorithm registration and discovery
115+
- Plugin-style architecture
116+
- Used in `fusion/modules/*/registry.py`
117+
118+
## Current Development Focus
119+
120+
As of the latest commits, the project is focused on:
121+
1. Quality improvements: Resolving linting errors and test failures
122+
2. Configuration system enhancements
123+
3. Documentation improvements
124+
4. Survivability experiment features (v1)
125+
5. Offline RL policy integration
126+
127+
## Reference Documents
128+
129+
For detailed information, consult:
130+
- `ARCHITECTURE.md`: System architecture and design
131+
- `CODING_STANDARDS.md`: Code style and organization
132+
- `TESTING_STANDARDS.md`: Testing requirements
133+
- `DEVELOPMENT_WORKFLOW.md`: Development process and tools
134+
- `CONTRIBUTING.md`: Contribution guidelines
135+
136+
## Working with This Codebase
137+
138+
When making changes:
139+
1. Read relevant module READMEs first
140+
2. Check `TODO.md` files for known issues
141+
3. Follow the standardized naming conventions
142+
4. Add tests for new functionality
143+
5. Update documentation as needed
144+
6. Run `make check-all` before committing
145+
7. Use the TodoWrite tool to track multi-step tasks
146+
147+
## Key Files to Know
148+
149+
- `fusion/core/simulation.py`: Main simulation engine
150+
- `fusion/interfaces/factory.py`: Algorithm factory and pipeline
151+
- `fusion/cli/run_sim.py`: CLI entry point
152+
- `fusion/configs/cli_to_config.py`: Configuration processing
153+
- `fusion/modules/*/registry.py`: Algorithm registries
154+
155+
## Domain Knowledge
156+
157+
### Optical Networking Concepts
158+
- **Spectrum slots**: Frequency spectrum divided into assignable units
159+
- **Wavelength**: Individual optical carrier
160+
- **Modulation formats**: BPSK, QPSK, 16-QAM, etc.
161+
- **SNR (Signal-to-Noise Ratio)**: Quality metric for optical signals
162+
- **Guard bands**: Spacing between spectrum assignments
163+
- **Fragmentation**: Inefficient use of spectrum due to non-contiguous allocations
164+
165+
### Network Survivability
166+
- **Protection**: Pre-provisioned backup resources (1+1, 1:1)
167+
- **Restoration**: Dynamic re-routing after failure
168+
- **SRLG (Shared Risk Link Group)**: Links that fail together
169+
- **Disjoint paths**: Paths sharing no common links/nodes
170+
171+
This context should help AI assistants understand the project structure, conventions, and domain when assisting with development tasks.

‎CODE_OF_CONDUCT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ This Code of Conduct applies both within project spaces and in public spaces whe
3434

3535
## Enforcement
3636

37-
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [your email address]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
37+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue in the GitHub issue tracker or by contacting the project maintainers. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
3838

3939
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
4040

‎CONTRIBUTING.md‎

Lines changed: 54 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Contributing to the Simulator
1+
# Contributing to FUSION
22

3-
Thank you for your interest in contributing to the simulator! We value your contributions and want to make the process as smooth as possible for everyone involved. This document outlines how you can contribute, our coding guidelines, the pull request process, and our code of conduct.
3+
Thank you for your interest in contributing to FUSION! We value your contributions and want to make the process as smooth as possible for everyone involved. This document outlines how you can contribute, our coding guidelines, the pull request process, and our code of conduct.
44

55
## Introduction
66

7-
This simulator is an open-source initiative, and we welcome contributions from everyone. Whether you're fixing a bug, adding a new feature, or improving documentation, your help is appreciated. Before contributing, please take a moment to read through this document to understand our processes and guidelines.
7+
FUSION is an open-source initiative, and we welcome contributions from everyone. Whether you're fixing a bug, adding a new feature, or improving documentation, your help is appreciated. Before contributing, please take a moment to read through this document to understand our processes and guidelines.
88

99
## How to Contribute
1010

@@ -16,57 +16,73 @@ This simulator is an open-source initiative, and we welcome contributions from e
1616

1717
## Coding Guidelines
1818

19-
### 1. Naming Conventions
19+
FUSION follows strict coding standards to ensure consistency and maintainability. Please review our comprehensive coding standards document before contributing:
2020

21-
1. **Helper Scripts**: Files in the `helper_scripts` directory should be named using the
22-
pattern `<script_name>_helpers.py`.
23-
2. **Data Structures**: Name variables with their type, e.g., `<name>_list`, `<name>_dict`, `<name>_set`.
24-
3. **Class Properties**: Include a dictionary named `<ClassName>_props` in class constructors for properties.
25-
4. **Inner Classes**: Name classes within a constructor `<ClassName>_Obj` to indicate scope and relationship.
21+
**See [CODING_STANDARDS.md](CODING_STANDARDS.md) for complete guidelines.**
2622

27-
### 2. Directory and File Structure
23+
### Key Highlights
2824

29-
1. **Argument Scripts**: Place external files with arguments in the `arg_scripts` directory,
30-
named `<file_name>_args.py`.
31-
2. **Module Naming**: Directories with Python scripts should follow `<name>_scripts` naming convention.
25+
1. **Naming Conventions**:
26+
- Functions: `snake_case` verbs (e.g., `load_config`, `validate_data`)
27+
- Classes: `PascalCase`
28+
- Use type hints instead of type suffixes in variable names
3229

33-
### 3. Coding Practices
30+
2. **Code Organization**:
31+
- Files should be under 500 lines
32+
- Functions should be under 50 lines
33+
- Each module must have a `README.md`
34+
- Tests in `tests/` subdirectory within each module
3435

35-
1. **Function Names**: Use assertive and descriptive names like `get`, `create`, `update`.
36-
2. **Type Annotations**: Explicitly list variable types in all function parameters.
37-
3. **Commenting and Documentation**:
38-
- Use `# FIXME:` for areas needing future fixes, with a brief explanation if necessary.
39-
- Use `# TODO:` for planned enhancements or tasks, with a concise description.
40-
4. **Argument Labeling**: Label arguments explicitly when calling functions.
36+
3. **Type Annotations**:
37+
- All function parameters and returns must have type annotations
38+
- Use modern Python type hints
4139

42-
### 4. Testing and Quality Assurance
40+
4. **Documentation**:
41+
- Use Sphinx-style docstrings
42+
- Use `# TODO:` for planned enhancements
43+
- Use `# FIXME:` for areas needing fixes
4344

44-
1. **Comprehensive Testing**: Test every function and its branches thoroughly.
45-
2. **Formatting**: Use an auto-formatting tool to maintain consistent code formatting, adhering to a style guide like
46-
PEP 8.
47-
48-
### 5. Additional Considerations
49-
50-
1. **Class and File Naming Alignment**: Ensure class names match their `.py` file names.
51-
2. **Argument Documentation**: Comment each argument in argument scripts to explain its purpose and expected values.
45+
5. **Quality Tools**:
46+
- Format code with `ruff`
47+
- Type check with `mypy`
48+
- Test with `pytest`
49+
- Run `make check-all` before submitting
5250

5351
## Pull Request Process
5452

55-
1. Fork the repository and create your branch from `main`.
56-
2. Ensure any install or build dependencies are removed before the end of the layer when doing a build.
57-
3. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is semantic.
58-
4. You may merge* the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
59-
60-
*Check to ensure that your pull request meets the requirements as outlined by the [PR template](https://github.com/SDNNetSim/FUSION/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md) before merging.
53+
1. **Fork and Branch**: Fork the repository and create your branch from `main`.
54+
2. **Code Quality**: Ensure your code passes all quality checks:
55+
```bash
56+
make format # Auto-format code
57+
make lint-new # Check for issues
58+
make test-new # Run tests with coverage
59+
make check-all # Comprehensive validation
60+
```
61+
3. **Documentation**: Update relevant documentation and add tests for new features.
62+
4. **Versioning**: Follow semantic versioning for any version changes.
63+
5. **PR Template**: Fill out the PR template completely when submitting.
64+
6. **Review**: You need sign-off from two other developers before merging.
65+
66+
Check the [PR template](https://github.com/SDNNetSim/FUSION/blob/main/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md) for specific requirements.
6167

6268
## Issue Reporting Process
63-
The github issue tracker is our primary medium for raising and resolving issues. Specific information related to reporting bugs and requesting features can be found below.
69+
70+
The GitHub issue tracker is our primary medium for raising and resolving issues.
6471

6572
### Bug Reports
66-
For bug reports, please be sure the structure of your report is consistent with the [bug report](https://github.com/SDNNetSim/FUSION/blob/main/.github/issue_template/01_bug_report.yml) template.
73+
When reporting bugs, please use the [bug report template](https://github.com/SDNNetSim/FUSION/blob/main/.github/issue_template/01_bug_report.yml) and include:
74+
- Clear description of the issue
75+
- Steps to reproduce
76+
- Expected vs actual behavior
77+
- Environment details (OS, Python version, etc.)
78+
- Relevant logs or error messages
6779

6880
### Feature Requests
69-
For feature requests, please be sure the structure of your request is consistent with the [feature request](https://github.com/SDNNetSim/FUSION/blob/main/.github/issue_template/02_feature_request.yml) template.
81+
When requesting features, please use the [feature request template](https://github.com/SDNNetSim/FUSION/blob/main/.github/issue_template/02_feature_request.yml) and include:
82+
- Clear description of the proposed feature
83+
- Use case and motivation
84+
- Potential implementation approach
85+
- Any relevant examples or references
7086

7187

7288
## Code of Conduct

0 commit comments

Comments
 (0)