physics_mcp/source/CONTRIBUTING.md

# PhysicsNeMo Contribution Guide

## Introduction

Welcome to Project PhysicsNeMo! We're excited you're here and want to contribute.
This documentation is intended for individuals and institutions interested in
contributing to PhysicsNeMo. PhysicsNeMo is an open-source project and, as such, its
success relies on its community of contributors willing to keep improving it.
Your contribution will be a valued addition to the code base; we simply ask
that you read this page and understand our contribution process, whether you
are a seasoned open-source contributor or whether you are a first-time
contributor.

### Communicate with Us

We are happy to talk with you about your needs for PhysicsNeMo and your ideas for
contributing to the project. One way to do this is to create an issue discussing
your thoughts. It might be that a very similar feature is under development or
already exists, so an issue is a great starting point. If you are looking for an
issue to resolve that will help, refer to the
[issue](https://github.com/NVIDIA/physicsnemo/issues) section.
If you are considering collaborating with NVIDIA PhysicsNeMo team to enhance PhysicsNeMo,
fill this [proposal form](https://forms.gle/fYsbZEtgRWJUQ3oQ9) and
we will get back to you.

## Contribute to PhysicsNeMo-Core

### Pull Requests

Developer workflow for code contributions is as follows:

1. Developers must first [fork](https://help.github.com/en/articles/fork-a-repo)
the [upstream](https://github.com/NVIDIA/physicsnemo) PhysicsNeMo repository.

2. Git clone the forked repository and push changes to the personal fork.

3. Once the code changes are staged on the fork and ready for review, a
[Pull Request](https://help.github.com/en/articles/about-pull-requests) (PR)
can be [requested](https://help.github.com/en/articles/creating-a-pull-request)
to merge the changes from a branch of the fork into a selected branch of upstream.

    - Exercise caution when selecting the source and target branches for the PR.
    - Ensure that you update the [`CHANGELOG.md`](CHANGELOG.md) to reflect your contributions.
    - Creation of a PR creation kicks off CI and a code review process.
    - Atleast one PhysicsNeMo engineer will be assigned for the review.

4. The PR will be accepted and the corresponding issue closed after adequate review and
testing has been completed. Note that every PR should correspond to an open issue and
should be linked on Github.

### Licensing Information

All source code files should start with this paragraph:

```bash
# SPDX-FileCopyrightText: Copyright (c) 2023 - 2024 NVIDIA CORPORATION & AFFILIATES.
# SPDX-FileCopyrightText: All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
```

### Signing Your Work

- We require that all contributors "sign-off" on their commits. This certifies that the
contribution is your original work, or you have rights to submit it under the same
license, or a compatible license.

  - Any contribution which contains commits that are not Signed-Off will not be accepted.

- To sign off on a commit you simply use the `--signoff` (or `-s`) option when
committing your changes:

  ```bash
  git commit -s -m "Add cool feature."
  ```

  This will append the following to your commit message:

  ```text
  Signed-off-by: Your Name <your@email.com>
  ```

- Full text of the DCO:

  ```text
    Developer Certificate of Origin
    Version 1.1

    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
    1 Letterman Drive
    Suite D4700
    San Francisco, CA, 94129

    Everyone is permitted to copy and distribute verbatim copies of this license 
    document, but changing it is not allowed.
  ```

  ```text
    Developer's Certificate of Origin 1.1

    By making a contribution to this project, I certify that:

    (a) The contribution was created in whole or in part by me and I have the right to 
    submit it under the open source license indicated in the file; or

    (b) The contribution is based upon previous work that, to the best of my knowledge,
    is covered under an appropriate open source license and I have the right under that
    license to submit that work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am permitted to submit under a
    different license), as indicated in the file; or

    (c) The contribution was provided directly to me by some other person who certified
    (a), (b) or (c) and I have not modified it.

    (d) I understand and agree that this project and the contribution are public and
    that a record of the contribution (including all personal information I submit with
    it, including my sign-off) is maintained indefinitely and may be redistributed
    consistent with this project or the open source license(s) involved.

  ```

### Pre-commit

For PhysicsNeMo development, [pre-commit](https://pre-commit.com/) is **required**.
This will not only help developers pass the CI pipeline, but also accelerate reviews.
Contributions that have not used pre-commit will *not be reviewed*.

`pre-commit` is installed as part of the `dev` optional dependencies defined in `pyproject.toml`.
To install `pre-commit` in an existing environment, follow the below steps inside the PhysicsNeMo
repository folder:

```bash
pip install pre-commit
pre-commit install
```

Once the above commands are executed, the pre-commit hooks will be activated and all
the commits will be checked for appropriate formatting.

### Continuous Integration (CI)

To ensure quality of the code, your merge request (MR) will pass through several CI checks.
It is mandatory for your MRs to pass these pipelines to ensure a successful merge.
Please keep checking this document for the latest guidelines on pushing code. Currently,
The pipeline has following stages:

1. `format`
    *Pre-commit will check this for you!* Checks for formatting of your
    Python code, using `ruff format` via [Ruff](https://docs.astral.sh/ruff/).
    If your MR fails this test, run `ruff format <script-name>.py` on
    problematic scripts and Ruff will take care of the rest.

2. `interrogate`
   *Pre-commit will check this for you!*
   Checks if the code being pushed is well documented. The goal is to make the
   documentation live inside code. Very few exceptions are made.
   Elements that are fine to have no documentation include `init-module`, `init-method`,
   `private` and `semiprivate` classes/functions and `dunder` methods. For definitions of
   these, refer [interrogate](https://interrogate.readthedocs.io/en/latest/). Meaning for
   some methods/functions is very explicit and exceptions for these are made. These
   include `forward`, `reset_parameters`, `extra_repr`, `MetaData`. If your MR fails this
   test, add the missing documentation. Take a look at the pipeline output for hints on
   which functions/classes need documentation.
   To test the documentation before making a commit, you can run the following during
   your development

    ```bash
    interrogate \
      --ignore-init-method \
      --ignore-init-module \
      --ignore-module \
      --ignore-private \
      --ignore-semiprivate \
      --ignore-magic \
      --fail-under 99 \
      --exclude '[setup.py]' \
      --ignore-regex forward \
      --ignore-regex reset_parameters \
      --ignore-regex extra_repr \
      --ignore-regex MetaData \
      -vv \
      --color \
      ./physicsnemo/
    ```

3. `lint`
    *Pre-commit will check this for you!*
    Linters will perform static analysis to check the style, complexity, errors
    and more. For markdown files `markdownlint` is used, its suggested to use
    the vscode, neovim or sublime
    [extensions](https://github.com/DavidAnson/markdownlint#related).
    PhysicsNeMo uses `ruff check` via[Ruff](https://docs.astral.sh/ruff/) for
    linting of various types. Currently we use flake8/pycodestyle (`E`),
    Pyflakes (`F`), flake8-bandit (`S`), isort (`I`), and performance 'PERF'
    rules. Many rule violations will be automatically fixed by Ruff; others may
    require manual changes.

4. `license`
    *Pre-commit will check this for you!*
    Checks for correct license headers of all files.
    To run this locally use `make license`.
    See the Licensing Information section above for details about the license header required.

5. `pytest`
    Checks if the test scripts from the `test` folder run and produce desired outputs. It
    is imperative that your changes don't break the existing tests. If your MR fails this
    test, you will have to review your changes and fix the issues.
    To run pytest locally you can simply run `pytest` inside the `test` folder.

    While writing these tests, we encourage you to make use of the [`@import_of_fail`](https://github.com/NVIDIA/physicsnemo/blob/main/test/pytest_utils.py#L25)
    decorator to appropriately skip your tests for developers and users not having your
    test specific dependencies. This mechanism helps us provide a better developer and
    user experience when working with the unit tests.

    Some of the tests require test data to be run; otherwise, they will be skipped.
    To get the data (available to NVIDIANs only), set the `TEST_DATA_DIR` environment variable
    to a desired value and run make get-data. After that, pytest will use the same
    variable to find the test data. Alternatively, you can pass it explicitly using
    `pytest --nfs-data-dir=<path to test data>`.

6. `doctest`
    Checks if the examples in the docstrings run and produce desired outputs.
    It is highly recommended that you provide simple examples of your functions/classes
    in the code's docstring itself.
    Keep these examples simple and also add the expected outputs.
    Refer [doctest](https://docs.python.org/3/library/doctest.html) for more information.
    If your MR fails this test, check your changes and the docstrings.
    To run doctest locally, you can simply run `pytest --doctest-modules` inside the
    `physicsnemo` folder.

7. `coverage`
    Checks if your code additions have sufficient coverage.
    Refer [coverage](https://coverage.readthedocs.io/en/6.5.0/index.html#) for more details.
    If your MR fails this test, this means that you have not added enough tests to the `test`
    folder for your module/functions.
    Add extensive test scripts to cover different
    branches and lines of your additions.
    Aim for more than 80% code coverage.
    To test coverage locally, run the `get_coverage.sh` script from the `test` folder and
    check the coverage of the module that you added/edited.