Skip to content

ComFiT documentation

ComFiT (Github) is a versatile Python library for simulating field theories, including plotting and animation in an object-oriented manner. If you use ComFiT in your research, please cite the following paper:

Skogvoll, V., & Rønning, J. (2024). ComFiT: A Python library for computational field theory with topological defects. Journal of Open Source Software, 9(98), 6599. https://doi.org/10.21105/joss.06599

Tutorials

The best way to get to know ComFiT is by using it in one of the following tutorials.

Base System

Basic Framework

Understand the basics of ComFiT, how to calculate derivatives and produce plots and animations in 1, 2 and 3 dimensions.

How to make your own model

Learn how to implement, solve and animate your own partial differential equation.

Quantum Mechanics

1D wave packets

Understand the basics of the Quantum Mechanics model.

2D wave packets

Understand how to plot a quantum mechanical system in 2 dimensions.

3D wave packets

Understand how to plot a quantum mechanical system in 3 dimensions.

The harmonic oscillator

Investigate the quantum mechanical harmonic oscillator.

The hydrogen atom

Get to know the hydrogen atom.

Bose-Einstein Condensates

Basic Framework

Understand the basics of the Bose Einstein Condensate model.

Time-dependent potentials

Learn how to create time-dependent potentials to stir the Bose Einstein Condensate model.

Comoving frame and defect tracking

Learn how to track defects and study defects made by an obstacle.

3D and comoving frame

Learn how to use the Bose Einstein Condensate model in 3 dimensions and in a comoving frame.

Nematic Liquid Crystal

2D active nematic

Simulate an active nematic liquid crystal in 2 dimensions.

Phase-field crystal

Basic framework

Get to know the basic of the PFC framework, including how to insert dislocations, plot them, and evolve the PFC.

Stresses and strains

Learn how to calculate stresses and strains in the PFC model.

Polycrystalline systems

Create polycrystalline systems with the PFC model and evolve it according to different dynamics.

For the time being, ComFiT is limited to periodic boundary conditions, but this may change in the future.

Installation

Comfit can be installed from the Python Package Index (PyPI), a repository of software for the Python programming language, by executing the command

pip install comfit

pip install comfit in your terminal or command prompt.

Virtual environnement

Using a virtual environnement when using ComFiT is highly encouraged for because even though we try to write robust code, it is still a library under development, so previously written simulations may break. By keeping your simulations together with the specific version of ComFiT, you make sure that your simulations will not break due to coming updates.

To create a virtual environnement, run the following command in your terminal after having navigated to the root folder of your exploration project

Python -m venv myvenv

This will create the folder myvenv which will contain the local installation of Python and associated packages. To activate the virtual environnement, simply run

.\venv\Scripts\activate

from the terminal. Afterwards, you may install ComFiT using PyPi. If your folder is part of a github repository, it is recommended to remove the virtual environment from the git project by adding venv/ to your .gitignore file.

Contributing

We welcome contributions. Whether you're fixing a bug, adding a new feature, or improving our documentation, your support helps us make the package more robust and versatile. Contributions can take many forms, from fixing minor bugs to implementing complex new features. Below are the ways you can contribute:

Bug Fixes

Did you identify a bug? Here's how to proceed:

  1. Fork the repository: Start by forking the ComFiT GitHub repository.
  2. Create a branch: Make a new branch on your fork dedicated to the bug fix.
  3. Fix the bug: Make the necessary changes to resolve the bug.
  4. Run tests: Ensure all existing tests pass with your changes. Add new tests if necessary to cover the bug fix.
  5. Submit a Pull Request (PR): Create a PR against the main ComFiT repository. Clearly describe the bug and how your changes fix it.

Reporting Issues

Encountered an issue or have a suggestion? Please follow these steps:

  1. Check existing issues: Before creating a new issue, please check existing issues to avoid duplicates.
  2. Create a new issue: If your issue is unique, open a new issue on GitHub. Provide a detailed description, including steps to reproduce the issue if applicable.

Feature Requests

Got an idea for a new feature or enhancement? We'd love to hear it! Please raise a discussion, or an issue as outlined above, detailing your idea and its potential benefits to ComFiT.

Adding Your Own Model

If you're interested in adding your own model to ComFiT, we welcome your contribution! Your model should adhere to the following guidelines:

  1. Well-documented: Include detailed documentation explaining your model's theory, implementation, and usage.
  2. Thoroughly tested: Write comprehensive tests covering the functionality of your model.
  3. Follow ComFiT structure: Ensure your model integrates seamlessly with the existing ComFiT framework.
  4. Tutorial: Consider adding a tutorial in the form of a Jupyter notebook, demonstrating how to use your model. Link to the tutorial in your contribution.

For detailed instructions on implementing your own PDE model with ComFiT, refer to our tutorial for creating your own model.

Documentation Improvements

Good documentation is key to a project's usability and its community's growth. If you see areas for improvement or want to add documentation for undocumented features, your contributions are greatly appreciated.