Merge branch 'readme' into 'main'

Create readme file

See merge request qt/kwant-scf!12

AUTHORS.md

+# pymf authors
+
+## Current pymf maintainers
+- Kostas Vilkelis
+- R. Johanna Zijderveld
+- Anton R. Akhmerov
+- Antonio L.R. Manesco
+
+## Other contributors
+- Isidora Araya Day
+- José L. Lado
+
+## Funding

LICENSE

+BSD 2-Clause License
+
+Copyright (c) 2024, pymf authors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

-# Project Name
+# `pymf`
 
-## Research Goal
+## What is `pymf`?
 
-## Research Plan
+`pymf` is a Python package that performs self-consistent Hartree-Fock calculations on tight-binding models.
+It aims to find the groundstate of a Hamiltonian with density-density interactions
 
-## Working on this project
-Configure the project by running
+$$
+\hat{H} = \hat{H_0} + \hat{V} = \sum_{ij} h_{ij} c^\dagger_{i} c_{j} + \frac{1}{2} \sum_{ij} v_{ij} \hat{n}_i \hat{n}_j,
+$$
 
-    ./setup
+and computes the mean-field correction $\hat{V}_{\text{MF}}$ which approximates the interaction term:
+
+$$
+\hat{V} \approx \hat{V}_{\text{MF}} = \sum_{ij} \tilde{v}_{ij} c^\dagger_{i} c_{j}.
+$$
+
+For more details, refer to the [theory overview](docs/source/documentation/mf_notes.md) and [algorithm description](docs/source/documentation/algorithm.md).
+
+## How to use `pymf`?
+
+The calculation of a mean-field Hamiltonian is a simple 3-step process:
+
+1. **Define**
+
+    To specify the interacting problem, use a `Model` object which collects:
+    - Non-interacting Hamiltonian as a tight-binding dictionary.
+    - Interaction Hamiltonian as a tight-binding dictionary.
+    - Particle filling number in the unit cell.
+2. **Guess**
+
+    Construct a starting guess for the mean-field correction.
+
+3. **Solve**
+
+    Solve for the mean-field correction using the `solver` function and add it to the non-interacting part to obtain the total mean-field Hamiltonian.
+
+```python
+import pymf
+
+#Define
+h_0 = {(0,) : onsite, (1,) : hopping, (-1,) : hopping.T.conj()}
+h_int = {(0,) : onsite_interaction}
+model = pymf.Model(h_0, h_int, filling=2)
+
+#Guess
+guess = pymf.generate_guess(guess_hopping_keys, ndof)
+
+#Solve
+mf_correction = pymf.solver(model, guess)
+h_mf = pymf.add_tb(h_0, mf_correction)
+```
+
+For more details and examples on how to use the package, we refer to the [tutorials](docs/source/tutorial/hubbard_1d.md).
+
+## Why `pymf`?
+
+Here is why you should use `pymf`:
+
+* Simple
+
+    The workflow is straightforward.
+    Interface with `Kwant` allows easy creation of complicated tight-binding systems and interactions.
+
+* Extensible
+
+    `pymf`'s code is structured to be easy to understand, modify and extend.
+
+* Optimized numerical workflow
+
+    Introduces minimal overhead to the calculation of the mean-field Hamiltonian.
+
+
+## What `pymf` doesn't do (yet)
+
+Here are some features that are not yet implemented but are planned for future releases:
+
+- **Superconductive order parameters**. Mean-field Hamiltonians do not include pairing terms.
+- **General interactions**. We allow only density-density interactions (e.g. Coulomb) which can be described by a second-order tensor.
+- **Temperature effects**. Density matrix calculations are done at zero temperature.
+
+## Installation
+
+```
+pip install pymf
+```
+
+## Citing `pymf`
+
+If you have used `pymf` for work that has lead to a scientific publication, please cite us as:
+
+```bibtex
+@misc{pymf,
+  author = {Vilkelis, Kostas and Zijderveld,  R. Johanna and Akhmerov, Anton R. and Manesco, Antonio L.R.},
+  doi = {10.5281/zenodo.11149850},
+  month = {5},
+  title = {pymf},
+  year = {2024}
+}
+```

docs/source/index.md

@@ -11,8 +11,6 @@ kernelspec:
   name: python3
 ---
 
-# pymf
-
 ```{toctree}
 :hidden:
 :maxdepth: 1
@@ -32,23 +30,6 @@ documentation/algorithm.md
 documentation/pymf.md
 ```
 
-## What is pymf?
-
-
-## Why pymf?
-
-
-## How does pymf work?
-
-## What does pymf not do yet?
-
-* Superconductivity
-
-## Installation
-
-```bash
-pip install .
+```{include} ../../README.md
+:relative-docs: docs/source/
 ```
-## Citing
-
-## Contributing