Skip to content

Commit 544c1bf

Browse files
RandomDefaultUserRandomDefaultUser
committed
v0.1.0: First pre-alpha release of MALA.
2 parents f206204 + 66026f8 commit 544c1bf

File tree

89 files changed

+2472
-1207
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

89 files changed

+2472
-1207
lines changed

‎.gitlab-ci.yml‎

Lines changed: 28 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,45 @@
11
default:
2-
image: registry.hzdr.de/multiscale-wdm/surrogate-models/fesl/fesl
2+
image: $CI_REGISTRY_IMAGE:latest
33

44
# Change pip's cache and conda's package directories to be inside the project
55
# directory since we can only cache local items.
66
variables:
77
CONDA_PKGS_DIRS: "${CI_PROJECT_DIR}/conda/pkgs"
88
PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/pip"
99

10-
cache:
11-
paths:
12-
- conda/pkgs
13-
- .cache/pip
14-
policy: pull
15-
1610
stages:
11+
- build
1712
- setup
1813
- test
1914
- deploy
2015

2116
.env_setup: &env_setup
22-
- conda env create -q -f install/fesl_cpu_environment.yml
23-
- conda clean --tarballs --yes
24-
- source activate fesl-cpu
2517
- pip install -q -e .
2618

2719
.data_setup: &data_setup
2820
- cd ..
29-
- git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.hzdr.de/multiscale-wdm/surrogate-models/fesl/data fesl_data_repo
30-
- cd fesl_data_repo
21+
- git clone -b v0.1.2 https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/hzdr/mala/data mala_data_repo
22+
- cd mala_data_repo
3123
- git lfs install
32-
- bash ../fesl/install/data_repo_link/link_data_repo.sh `pwd`
33-
- cd ../fesl
24+
- bash ../mala/install/data_repo_link/link_data_repo.sh `pwd`
25+
- cd ../mala
26+
27+
build-image:
28+
stage: build
29+
image: docker:20.10
30+
services:
31+
- docker:20.10-dind
32+
before_script:
33+
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
34+
script:
35+
- docker pull $CI_REGISTRY_IMAGE:latest || true
36+
- docker build --cache-from $CI_REGISTRY_IMAGE:latest --tag $CI_REGISTRY_IMAGE:latest .
37+
- docker push $CI_REGISTRY_IMAGE:latest
38+
tags:
39+
- dind
3440

35-
setup-fesl:
41+
setup-mala:
3642
stage: setup
37-
cache:
38-
paths:
39-
- conda/pkgs
40-
- .cache/pip
41-
policy: pull-push
4243
before_script:
4344
- *env_setup
4445
- *data_setup
@@ -54,22 +55,23 @@ test-basic-functions:
5455
- *data_setup
5556
script:
5657
- cd test
57-
- python fesl_tests.py
58-
needs: [setup-fesl]
58+
- python mala_tests.py
59+
needs: [setup-mala]
5960

6061
test-workflow:
6162
stage: test
63+
tags:
64+
- performance
6265
before_script:
6366
- *env_setup
6467
- *data_setup
6568
script:
6669
- cd examples
6770
- python ex99_verify_all_examples.py
6871
- cd ..
69-
needs: [setup-fesl]
72+
needs: [setup-mala]
7073

7174
#### documentation
72-
7375
setup-docs:
7476
stage: setup
7577
image: python:3.7
@@ -97,7 +99,7 @@ test-docstrings:
9799
- pip install -qU pip
98100
- pip install -qU pydocstyle
99101
script:
100-
- pydocstyle --convention=numpy fesl
102+
- pydocstyle --convention=numpy mala
101103
needs: [setup-docs]
102104

103105
pages:
@@ -115,7 +117,7 @@ pages:
115117
- pip install -qU recommonmark
116118
- pip install -qU sphinx-markdown-tables
117119
script:
118-
- sphinx-apidoc -o docs/source/api fesl
120+
- sphinx-apidoc -o docs/source/api mala
119121
- sphinx-build -b html -d docs/_build/doctrees docs/source docs/_build/html
120122
after_script:
121123
- mv docs/_build/html public

‎Dockerfile‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
FROM continuumio/miniconda3:4.9.2
2+
3+
# Update the image to the latest packages
4+
RUN apt-get update && apt-get upgrade -y
5+
6+
RUN apt-get install --no-install-recommends -y build-essential \
7+
libz-dev swig git-lfs && \
8+
apt-get clean && rm -rf /var/lib/apt/lists/*
9+
10+
COPY install/mala_cpu_environment.yml .
11+
RUN conda env create -q -f mala_cpu_environment.yml && rm -rf /opt/conda/pkgs/*
12+
13+
RUN echo "source activate mala-cpu" > ~/.bashrc
14+
ENV PATH /opt/conda/envs/mala-cpu/bin:$PATH

‎README.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
FESL
1+
MALA
22
====
33

4-
FESL (Framework for Electronic Structure Learning) is a machine-learning
4+
MALA tools (Materials Analysis and Learning) is a machine-learning
55
based framework to enable multiscale modeling by bypassing
66
computationally expensive density functional simulations. It is designed
77
as a python package. This repository is structured as follows:
@@ -10,15 +10,15 @@ as a python package. This repository is structured as follows:
1010
1111
├── examples : contains useful examples to get you started with the package
1212
├── install : contains scripts for setting up this package on your machine
13-
├── fesl : the source code itself
13+
├── mala : the source code itself
1414
├── test : test scripts used during development, will hold tests for CI in the future
1515
└── docs : Sphinx documentation folder
1616
1717
1818
Installation
1919
------------
2020

21-
Please refer to :doc:`Installation of FESL <install/README>`.
21+
Please refer to `Installation of MALA <https://multiscale-wdm.pages.hzdr.de/surrogate-models/fesl/fesl/install/README.html>`_.
2222

2323
Running
2424
-------

‎docs/Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,4 @@ help:
2020
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
2121

2222
apidocs:
23-
sphinx-apidoc -f -o source/api ../fesl
23+
sphinx-apidoc -f -o source/api ../mala

‎docs/source/CONTRIBUTE.md‎

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,52 @@
1-
## Contributing to FESL
1+
## Contributing to MALA
2+
3+
MALA is open source software and as such always welcomes additions and
4+
improvements. However, we kindly ask any contributor to adhere to the following
5+
suggestions in order to keep the overall quality and maintainability of the
6+
code high.
7+
8+
## Versioning and releases
9+
10+
MALA has a versioning system. The version number is only updated when merging
11+
on `master`. This constitues a release. Please note that not all changes
12+
to code constitute such a release and generally, merges will be directed
13+
to the `develop` branch
14+
(see [branching strategy](#branching-strategy)). The version number has
15+
the form `MAJOR.MINOR.FIX`:
16+
17+
* `MAJOR`: Big changes to the code, that fundamentally change the way it
18+
functions or wrap up a longer development.
19+
* `MINOR`: new features have beend added to the code.
20+
* `FIX`: A bug in a feature has been fixed.
221

3-
Some introductory text ...
422

523
## Branching strategy
624

7-
In general, contributors should develop on branches based off of `master` and merge requests should be to `master`.
25+
In general, contributors should develop on branches based off of `develop` and
26+
merge requests should be to `develop`. Please choose a descriptive branch name,
27+
ideally incorporating some identifying information (such as your initials)
28+
or the starting date of your developments. Branches from `develop` to `master`
29+
will be done after prior consultation of the core development team.
30+
31+
## Developing code
32+
33+
* Regularly check your code for PEP8 compliance
34+
* Make sure all your classes, functions etc. are documented properly,
35+
follow the
36+
[NumPy style](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard)
37+
for docstrings
38+
* Keep your code object-oriented, modular, and easily reusable
39+
* Add tests and examples for sizable new features
840

941
## Submitting a merge request
1042

11-
- ensure that your documentation of classes, functions etc. follow the [NumPy style](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) for docstrings
12-
- rebase your branch onto `master` before submitting a merge request
43+
* Ensure that you followed the guidelines for [developing code](#developing-code)
44+
* Rebase your branch onto `develop` before submitting a merge request
45+
* Only assign yourself to a merge request when time does not permit an
46+
external check
1347

1448
## Issues
1549

16-
...
50+
* Use issues to document potential enhancements, bugs and such
51+
* Please tag your issues, and consider setting up a deadline
52+

‎docs/source/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
# -- Project information -----------------------------------------------------
2222

23-
project = 'FESL'
23+
project = 'MALA'
2424
copyright = '2021, HZDR'
2525
author = 'HZDR'
2626

‎docs/source/features/background.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
Background
2+
===========
3+
4+
Workflow
5+
*********
6+
7+
The goal of MALA is to build surrogate models for electronic structure theory.
8+
These surrogate models are based on neural networks. After training such
9+
a model, it allows the fast evaluation of the total energy and atomic forces.
10+
MALA is build around Density Functional Theory, but can in
11+
principle be used with all electronic structure methods that calculate the
12+
total energy and atomic forces given atomic positions as input.
13+
Building these surrogate models requires preprocessing
14+
:doc:`preprocessing <preprocessing>` of the data, training of a
15+
:doc:`neural network <neuralnetworks>` and
16+
:doc:`postprocessing <postprocessing>` of the results.
17+
MALA is designed for the investigation of systems at non-zero temperatures and
18+
operates in a "per-grid-point" manner, meaning that every grid point of a
19+
simulation cell is passed through the network individually.
20+
21+
Density Functional Theory
22+
*************************
23+
24+
Density Functional Theiry is one of the most popular electronic structure
25+
calculation methods due to its combination of reasonable accuracy and
26+
computational cost.
27+
In DFT, the central quantity is the electronic density of a given system.
28+
Within the Kohn-Sham framework, this density is given by
29+
30+
.. math::
31+
32+
n(\boldsymbol{r}) = \sum_j f^\beta(\epsilon_j)\,
33+
|\phi_j(\boldsymbol{r})|^2 \; .
34+
35+
Here, :math:`\phi_j(\boldsymbol{r})` denote the Kohn-Sham wave functions,
36+
which are given by the Kohn-Sham equations
37+
38+
.. math::
39+
40+
\left[-\frac{1}{2}\nabla^2 + v_\mathrm{{\scriptscriptstyle S}}(\mathbf{r};
41+
\underline{\boldsymbol{R}})\right] \phi_j(\boldsymbol{r};
42+
\underline{\boldsymbol{R}}) = \epsilon_j \phi_j(\boldsymbol{r};
43+
\underline{\boldsymbol{R}}) \; ,
44+
45+
which give a system of non-interacting particles restricted to reproduce
46+
the density of the interacting system. The total energy is evaluated using
47+
48+
.. math::
49+
50+
E_\mathrm{total}(\underline{\boldsymbol{r}}) =
51+
T_\mathrm{{\scriptscriptstyle S}}
52+
[n](\underline{\boldsymbol{r}}) -
53+
S_\mathrm{{\scriptscriptstyle S}}
54+
[n](\underline{\boldsymbol{r}})/\beta
55+
+ E_\mathrm{{\scriptscriptstyle H}}
56+
[n](\underline{\boldsymbol{r}}) +
57+
E_\mathrm{{\scriptscriptstyle XC}}[n](\underline{\boldsymbol{r}})
58+
+ E^{ei}[n](\underline{\boldsymbol{r}})+ E^{ii} + \mu N_e \; .
59+
60+
Forces and other quantities of interest can be derived from the total energy.

‎docs/source/features/neuralnetworks.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Neural Networks
2+
=================
3+
4+
Neural networks are powerful machine learning tools in principle capable of
5+
approximating any function. In MALA, neural networks are built using PyTorch.
6+
Hyperparameter optimization can be done using optuna and custom routines.

‎docs/source/features/postprocessing.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Postprocessing
2+
==============
3+
4+
MALA provides routines to calculate quantities of interests from the physical
5+
data such as the LDOS, DOS and electronic density.
6+
7+
LDOS
8+
*****
9+
10+
The LDOS can be used to calculate the number of electrons and band energy
11+
(both via the DOS) and the total energy (via the DOS and the electronic
12+
density) of a system. In order to do that, the LDOS is usually integrated
13+
either on the spatial or the energy grid, yielding the DOS or density
14+
respectively.
15+
16+
DOS
17+
***
18+
19+
The DOS can be used to calculate the number of electrons and band energy
20+
as well as the entropy contribution to the total energy.
21+
22+
23+
Density
24+
*******
25+
26+
The Density can be used to calculate the number of electrons and density
27+
based contributions to the total energy.

‎docs/source/features/preprocessing.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Preprocessing
2+
==============
3+
4+
Descriptors
5+
***********
6+
7+
The input data for MALA are, in theory, the atomic positions. As MALA
8+
oeprates "per-grid-point" manner, information from the atomic positions have
9+
to be present on the entire grid of the simulation cell. This is done by
10+
calculating descriptors on the grid. Currently, only SNAP descriptors are
11+
supported. MALA uses LAMMPS to calculate these SNAP descriptors.
12+
13+
Targets
14+
***********
15+
16+
MALA is optimized for the usage of the LDOS (local density of states) as
17+
target quantity. The LDOS gives the DOS (density of states) at each grid point,
18+
and thus gives information on the energy-grid as well as the 3D grid.
19+
The LDOS can be used to :doc:`efficiently calculate quantities of interest.
20+
<postprocessing>` MALA provides parsing routines to read the LDOS from
21+
DFT calculations.

0 commit comments

Comments
 (0)