Skip to content

Latest commit

 

History

History
89 lines (62 loc) · 2.86 KB

contributing.md

File metadata and controls

89 lines (62 loc) · 2.86 KB

Contributing and Extending PyMAD-NG

This guide is for developers who want to contribute to PyMAD-NG or extend its capabilities. It outlines the structure of the codebase, how to develop new features, and best practices for writing and testing code.

Overview of Repository Structure

File / Module Purpose
src/pymadng/madp_object.py Contains the main {class}pymadng.MAD class and high-level interface
src/pymadng/madp_pymad.py Manages subprocess communication and type handling
src/pymadng/madp_classes.py Defines reference object wrappers (mad_ref, etc.)
src/pymadng/madp_last.py Manages temporary variables like _last[]
src/pymadng/madp_strings.py Utility for quoting and formatting MAD-compatible text
examples/ Contains working scripts and tutorials
tests/ Contains unit tests for the codebase
docs/ Documentation files

Getting Started

Prerequisites

  • Python 3.7+
  • numpy, pandas, and optionally tfs-pandas
  • A valid MAD-NG executable (either system or bundled)

Install PyMAD-NG in Editable Mode

To contribute to PyMAD-NG, clone the repository and install it in editable mode. This allows you to make changes and test them without reinstalling. In specific cases, you may be allowed write access to the MAD-NG.py repository. If so, you only need to clone the repository and install it in editable mode.

git clone https://github.com/<your-org>/MAD-NG.py.git
cd pymadng
pip install -e .

Development Workflow

  1. Create a Branch
git checkout -b your-feature-name

  1. Write Code

  2. Test Code

    • All tests are located in the tests/ directory, currently unittests are used.

  3. Run Tests

python -m unittest tests/*.py
  1. Submit a Pull Request
    • Include a clear description of the change
    • Reference any related issues

Best Practices

Code Style

  • Follow PEP8 (enforced via linters)
  • Use descriptive names for MAD objects (e.g. tw, flow, seq)
  • Keep high-level user APIs separate from internal helpers
  • Use Ruff for code and import formatting.

Documentation

  • Update or extend .md or .rst files as appropriate
  • Document new examples in the examples/ directory
  • Ensure all new features are at least in the API reference

Questions or Issues?

  • Open a GitHub Issue
  • Tag maintainers in your Pull Request
  • See the [Debugging Guide] or [Architecture Overview] for internals

Thanks for contributing to PyMAD-NG!