Development guide

Fork and Clone the Repository

1. Fork the repository on GitHub by clicking the “Fork” button

2. Clone the library and connect your fork:

   git clone https://github.com/neuraloperator/neuraloperator.git
   cd neuraloperator
   git remote rename origin upstream
   git remote add origin https://github.com/<YOUR_GIT_NAME>/neuraloperator.git
   git remote -v
   

   This should show:

   origin  https://github.com/<YOUR_GIT_NAME>/neuraloperator.git (fetch)
   origin  https://github.com/<YOUR_GIT_NAME>/neuraloperator.git (push)
   upstream        https://github.com/neuraloperator/neuraloperator.git (fetch)
   upstream        https://github.com/neuraloperator/neuraloperator.git (push)
   

Set Up Environment

1. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

2. Install development dependencies:

   pip install -e .[dev]
   # OR
   pip install neuraloperator[dev]
   

Create a Branch and Make Changes

# Create and switch to a new branch
git checkout -b feature/your-feature-name

# Make your changes
# ... edit files ...

# Stage and commit your changes
git add .
git commit -m "Add: brief description of your changes

- More detailed explanation of what you changed
- Why you made these changes
- Any relevant context"

# Push to your fork
git push -u origin feature/your-feature-name

Write Tests

Always add tests for new functionality!

• For models: Add tests in neuralop/models/tests/test_your_model.py

• For layers: Add tests in neuralop/layers/tests/test_your_layer.py

• For utilities: Add tests in the appropriate test directory

Example test structure:

import pytest
import torch
from neuralop.models import YourModel

class TestYourModel:
    def test_forward_pass(self):
        model = YourModel(...)
        x = torch.randn(1, 3, 32, 32)
        output = model(x)
        assert output.shape == expected_shape

    def test_gradient_flow(self):
        # Test that gradients flow properly
        pass

Run Tests and Quality Checks

# Run all tests
pytest neuralop

# Run tests with verbose output
pytest neuralop -v

# Run specific test file
pytest neuralop/models/tests/test_your_model.py

# Format code
black .

Submit a Pull Request

After having forked and cloned the repository as described in the Fork and Clone the Repository section, and created a branch and committed changes as described in the Create a Branch and Make Changes section, you can now submit your pull request:

1. Push your branch to your fork:

   git push -u origin feature/your-feature-name
   

2. Go to your fork on GitHub and you should see a banner suggesting to create a pull request, or click “Compare & pull request”.

3. Fill out the PR description:

   • Provide a clear title that describes your changes

   • Write a detailed description explaining what you’ve changed or added

   • Reference any related issues using #issue_number

   • Include screenshots or examples if applicable

4. Submit the pull request by clicking “Create pull request”.

Ensure your PR description clearly communicates what you have changed or added, why you made these changes, and any relevant context for reviewers.

Code Style

• Follow PEP 8 style guidelines for Python code

• Use meaningful names for variables, functions, and classes

• Write clear docstrings using NumPy docstring format

• Add type hints where appropriate

Code Formatting

Before submitting, ensure your code follows our style guide:

# Format with black
black .

Validate every update made by the black command

Testing Requirements

• All new code must have tests

• Run the full test suite before submitting PRs

• Use descriptive test names that explain what is being tested

• Test both normal operation and edge cases

• Aim for complete code coverage for new functionality

Building Documentation

The HTML documentation is built using Sphinx:

cd doc
make html

This builds the docs in ./doc/build/html. Note that documentation requires additional dependencies from ./doc/requirements_doc.txt.

To view documentation locally:

cd doc/build/html
python -m http.server 8000
# Visit http://localhost:8000

Git Best Practices

• Write clear, descriptive commit messages

• Keep commits focused and atomic (one logical change per commit)

• Rebase your branch on main before submitting PRs

• Use conventional commit format when possible (feat:, fix:, docs:, etc.)

Documentation Standards

To ensure code clarity and future maintainability, NeuralOperator adheres to simple style principles.

In general, docstrings use the NumPy format:

def function(arg1: type1, arg2: type2=default)
    """
    Parameters
    ----------
    arg1 : type1
        description of what arg1 'means'
        for the function's behavior
    arg2 : type2, optional
        description arg2
        by default default
    """

For classes, this docstring should go directly below the class declaration:

class MyClass(Superclass):
    """
    docstring goes here
    """
    def __init__(self, ...):
    # Full NumPy docstring not needed here.

We also adhere to good in-line commenting practices. When a block’s function is not obvious on its own, add in-line comments with a brief description. For tensor operations, shape annotations are especially helpful where applicable.

Adding a New Neural Operator Model

To add a new neural operator model:

1. Create a new file in neuralop/models/your_model.py

2. Implement the model as a subclass of BaseModel

3. Add comprehensive tests in neuralop/models/tests/test_your_model.py

4. Update imports in the appropriate __init__.py files

5. Add documentation with examples and mathematical formulations

Example structure:

from neuralop.models import BaseModel

class YourModel(BaseModel):
    """Your model docstring here."""

    def __init__(self, ...):
        super().__init__()
        # Your implementation

    def forward(self, x):
        # Your forward pass
        return x

Adding a New Layer

To add a new layer:

1. Create a new file in neuralop/layers/your_layer.py

2. Ensure the layer is a subclass of torch.nn.Module

3. Add comprehensive tests in neuralop/layers/tests/test_your_layer.py

4. Update imports in the appropriate __init__.py files

Before Asking for Help

1. Check the documentation and existing issues

2. Search GitHub issues for similar problems

3. Provide a minimal reproducible example

4. Include error messages and stack traces

5. Specify your environment (OS, Python version, PyTorch version)

Contact Methods

• GitHub Issues: Create an issue for bugs or feature requests

• GitHub Discussions: Use for questions and ideas

• Documentation: Check the official documentation