Skip to content

README and CONTRIBUTING #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethan-shanahan merged 2 commits into from
Sep 15, 2025
Merged

README and CONTRIBUTING #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc6f1ca
update README.md for clarity, parity, and removal of contributing info
Sep 9, 2025
5e1b309
isolated contributing info
Sep 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Contributing

If you are planning on contributing to AiiDA-FANS, please consider the following guidelines. Additionally, it is strongly recommended to use the pixi package manager to install the appropriate development environment. After cloning this repository, simply run `pixi install` and use the default environment.

## Development
1. Branch off `dev` with a name appropriate for what you are working on (e.g. `feat/myfeature` or `bug/badbug`).
2. Implement, commit, and push your changes.
3. Open a Pull Request into `dev` (e.g. `dev ← feat/myfeature`), then merge and delete your branch.

## Release
1. Open a Pull Request `main ← dev`, then merge but do **not** delete `dev`.
2. Draft a new Release and assign it a new Tag according to the new version number (e.g. `v1.2.3`).
3. Generate release notes and publish the Release.
60 changes: 20 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,69 +1,49 @@

# aiida-fans
# AiiDA-FANS

[![PyPI Package][pypi-badge]][pypi-link]
[![Docs Status][docs-badge]][docs-link]
[![Build Status][ci-badge]][ci-link]

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

This is a plugin for [AiiDA][aiida-link] that facilitates the use of [FANS][FANS-link]. FANS is an FFT-based homogenisation solver for microscale and multiphysics problems. It is an open-source project under active development at the Institute of Applied Mechanics, University of Stuttgart. This plugin aims to bring the full value of provenance tracking and database integration to the results produced by FANS.

The design goals of this plugin are primarily to provide as simplistic a user experience as is reasonably possible. Secondarily, more featureful additions will be made to extend the users' options for queryability and optimisation.
The design goals of this plugin are to provide a simple but powerful user interface to FANS. In doing so, the plugin packages additional utilities to eliviate some of the burdens we perceive in the traditional AiiDA workflow.

## Upcoming
**Please note:** This plugin is currently in the planning stage of development, with substantial contributions coming soon.

### Pre-launch
- [x] basic functionality capable of completing the example simulations presented by FANS with minimal database integration
- [x] documentation hosted on aiida-fans.readthedocs.io
- [x] documentation outline
- [x] publish package on PyPI
## Installation

### Post-launch
- [ ] documentation expansion
- [ ] input validation developed in cooperation with the FANS team
- [ ] file sharing optimisations
- [ ] greater database integration via output analysis/extraction
AiiDA-FANS is available on the PyPI and conda-forge channels. Our recommended method of installing AiiDA-FANS is to use the pixi package manager, in which case `pixi add aiida-fans` will install the plugin from conda-forge by default, as well as its dependencies: python, AiiDA, and h5py.

## Installation
The plugin is currently unavailable via PyPI at this stage in development, but it is intended to be published upon an upcoming functional release.
Otherwise, the package can be installed with pip by `pip install aiida-fans` or with mamba by `mamba install aiida-fans`.

The package can always be installed by cloning this repository and installing it locally like so...
In any case, the user is responsible for installing FANS and ensuring it is accessible to the plugin. This can be achieved without need for further customisation by having FANS accessible on the PATH environment variable. Please consult the [FANS repository][FANS-link] for more information on the installation of this software.

```bash
$ pip install ./aiida-fans
```

You must also ensure that FANS, AiiDA, and their various dependencies are installed. Please consult the [FANS repository][FANS-link] and the [AiiDA installation][aiida-install-link] guide for more information.
## Usage

## Contributing
To use this plugin, you must first establish an AiiDA profile, computer, and code. For help on how to do this please refer to the [AiiDA installation][AiiDA-install-link] guide.

### Development
1. Branch off `dev` with a name appropriate for what you are working on (e.g. `feat/myfeature` or `bug/badbug`).
2. Implement, commit, and push your changes.
3. Open a Pull Request `dev ← feat/myfeature`, then merge and delete.
For general information on the usage of AiiDA you should refer to the [AiiDA documentation][AiiDA-docs-link], and for the usage of FANS refer to its [repository][FANS-link].

### Release
1. Open a Pull Request `main ← dev`, then squash and merge.
2. Draft a new Release, named after the release version (e.g. v1.2.3).
3. Create and assaign a new Tag, identically named.
3. Generate release notes and publish.
This plugin offers some utilities to help smooth the AiiDA user experience. Namely, the `utils.run_fans` function which allows you to provide the inputs for a job as a dictionary of mostly pythonic values. This utility will parse these inputs and automatically use any appropriate existing nodes it finds in your profile before making new nodes where necessary. For more information on this plugin's specifics and how to use the utilities, please refer to the [documentation][docs-link].

## Tutorial

A tutorial accompanies this plugin. To try it out: clone this repository, cd into it, run `pixi install -e tutorial` and `marimo run tutorial/tutorial.py`. For more information before you begin, take a look at `./tutorial/README.md`.

## Contact

You can contact ethan.shanahan@gmail.com with regard to this plugin specifically.
You can contact ethan.shanahan@gmail.com with any questions regarding the AiiDA-FANS plugin and accompanying tutorial.

<!-- URLs -->
[pypi-badge]: https://badge.fury.io/py/aiida-fans.svg
[pypi-link]: https://badge.fury.io/py/aiida-fans
[release-badge]: https://img.shields.io/github/v/release/ethan-shanahan/aiida-fans?include_prereleases
[release-link]: https://github.com/ethan-shanahan/aiida-fans/releases
[ci-badge]: https://github.com/ethan-shanahan/aiida-fans/actions/workflows/ci.yml/badge.svg?branch=main
[ci-link]: https://github.com/ethan-shanahan/aiida-fans/actions
[cov-badge]: https://coveralls.io/repos/github/ethan-shanahan/aiida-fans/badge.svg?branch=main
[cov-link]: https://coveralls.io/github/ethan-shanahan/aiida-fans?branch=main
[docs-badge]: https://readthedocs.org/projects/aiida-fans/badge
[docs-link]: http://aiida-fans.readthedocs.io/

[aiida-link]: https://www.aiida.net/
[aiida-install-link]: https://aiida.readthedocs.io/projects/aiida-core/en/latest/installation/index.html
[AiiDA-docs-link]: https://aiida-core.readthedocs.io/
[AiiDA-install-link]: https://aiida.readthedocs.io/projects/aiida-core/en/latest/installation/index.html
[FANS-link]: https://github.com/DataAnalyticsEngineering/FANS