ovito-org / PythonPipelineSourceTemplate

Template repository for a Python-based pipeline source for OVITO

Python Pipeline Source Template

Template for a custom Python-based pipeline source that hooks into OVITO and can easily be shared with other users.

This repository contains a template for creating your own Python script pipeline source, which can be installed into OVITO Pro or the ovito Python module using pip. In opposite to using file-based pipeline sources, the python script piplines source allows you to generate ad-hoc contents direclty in OVITO.

Getting Started

1. Click the "Use this template" button to create your own repository based on this template.
2. Rename src/PackageName to reflect the name of your pipeline source.
3. Implement your custom pipeline source in src/PackageName/__init__.py. When you implement only the create method, just one static configuration (frame 0) will be generated. To generate a trajectory instead refer to the PipelineSourceInterface.compute_trajectory_length method as explained in the OVITO Python docs.
4. Fill in the pyproject.toml file. Fields that need to be replaced with your information are enclosed in descriptive [[field]] tags. Please make sure to include ovito>=3.9.2 as a dependency. Depending on your needs, you can add additional fields to the pyproject.toml file. Information can be found here.
5. Fill in the README_Template.md file. Again, the [[fields]] placeholders should guide you. Feel free to add other sections like "Images", "Citation", or "References" as needed.
6. Add meaningful examples and data sample files to the examples directory to help others understand the use of your pipeline source.
7. Pick a license for your project and replace the current (MIT) LICENSE file with your license. If you keep the MIT license, please update the name and year in the current file.
8. Once you're done, rename README_Template.md to README.md, replacing this file.

Testing

This repository is configured to enable automated testing using the pytest framework. Tests are automatically executed after each push to the main branch. To set up and activate automated testing, follow these two steps:

1. Write your tests in the test/test_pipeline_source.py file. You can also use other filenames that adhere to the pytest requirements.
2. Open the .github/workflows/python-tests.yml file and remove the if: ${{ false }} condition on line 15.

If needed, you can also adjust the operating system and Python versions by modifying the following lines:

os: [ubuntu-latest, macos-latest, windows-latest]
python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]

An example can be found here.

As of August 16, 2023, according to the GitHub documentation, "GitHub Actions usage is free for standard GitHub-hosted runners in public repositories, and for self-hosted runners." Please refer to the GitHub documentation if you are uncertain about incurring costs.