Get Involved#

Surfaces is an open-source project and we welcome contributions from the community.

Ways to Contribute#

There are many ways to help improve Surfaces:

Report Bugs#

Found a bug? Please open an issue on GitHub:

Search existing issues first
If not found, open a new issue
Include:
- Surfaces version
- Python version
- Operating system
- Minimal code to reproduce
- Full error traceback

Suggest Features#

Have an idea for a new feature or test function?

Check if it’s already been suggested
Open an issue describing:
- What you’d like to see
- Why it would be useful
- Example use cases

Improve Documentation#

Documentation improvements are always welcome:

Fix typos or unclear explanations
Add examples
Improve API documentation
Write tutorials

Submit Code#

Ready to contribute code?

Fork the repository
Create a feature branch
Make your changes
Write tests for new functionality
Ensure all tests pass
Submit a pull request

Development Setup#

To set up a development environment:

# Clone the repository
git clone https://github.com/SimonBlanke/Surfaces.git
cd Surfaces

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev,test]"

Running Tests#

Run the test suite:

# Run all tests
make test

# Run just pytest
make py-test

# Run linting
flake8

Code Style#

Please follow these guidelines:

Use black for code formatting
Follow PEP 8 style guidelines
Add docstrings to all public functions and classes
Include type hints where appropriate

Adding Test Functions#

Surfaces uses the template method pattern: public methods are fixed in base classes and delegate to private override points. See Template Method Pattern for the full architecture reference.

To add a new test function:

Create a new file in the appropriate category
Inherit from the appropriate base class
Implement the required override point(s) for that base class
Add to __init__.py exports
Write tests

Base Class	Required Overrides	Search Space
`AlgebraicFunction`	`_objective(params)`	Automatic from `default_bounds` + `n_dim`
`EngineeringFunction`	`_raw_objective(params)`, `_constraints(params)`	Automatic from `variable_names` + `variable_bounds`
`MachineLearningFunction`	`_ml_objective(params)`, `_default_search_space()`	Built from `para_names` + `*_default` attrs
`SimulationFunction`	`_setup_simulation()`, `_run_simulation(params)`, `_extract_objective(result)`, `_default_search_space()`	Explicit dict per function

Example: adding an algebraic function:

from surfaces.test_functions.algebraic._base_algebraic_function import AlgebraicFunction

class NewFunction(AlgebraicFunction):
    """Description of the function."""

    _spec = {
        "n_dim": 2,
        "default_bounds": (-5.0, 5.0),
        "convex": True,
    }

    f_global = 0.0
    x_global = [0.0, 0.0]

    def _objective(self, params):
        x = params["x0"]
        y = params["x1"]
        return x**2 + y**2

Code of Conduct#

Please be respectful and constructive in all interactions. We’re building a welcoming community for everyone interested in optimization.