Metadata-Version: 2.1
Name: hilde
Version: 0.2.1.dev1
Summary: Haber Institute Lattice Dynamics Environment
Home-page: https://github.com/flokno/hilde
License: ISC
Keywords: physics
Author: Florian Knoop
Author-email: knoop@fhi-berlin.mpg.de
Requires-Python: >=3.7,<4.0
Classifier: License :: OSI Approved
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Requires-Dist: ase (>=3.17,<4.0)
Requires-Dist: matplotlib (>=3.1,<4.0)
Requires-Dist: numpy (>=1.16,<2.0)
Requires-Dist: phonopy (>=2.1,<3.0)
Requires-Dist: scipy (>=1.3,<2.0)
Requires-Dist: son (>=0.1.4,<0.2.0)
Requires-Dist: spglib (>=1.12,<2.0)
Project-URL: Repository, https://github.com/flokno/hilde
Description-Content-Type: text/markdown

**Installation**

External dependencies:

```
apt-get install gfortran liblapack-dev liblapacke-dev mongodb
```

Install the python requirements in `requirements.txt` _in order_:

```
cat requirements.txt | xargs -n 1 -L 1 pip install --user
```

Configure Hilde by creating a `~/.hilderc` configuration file in the home directory:

```
cp hilde/location/hilderc.template ~/.hilderc
```

and edit according to system. The `aims_command` is a command or script that takes care
of running aims. This can be either just `mpirun aims.x`, or a script loading necessary
modules etc. and finally calling `srun aims.x` on a cluster.

Install Hilde:

```
pip install --user -U .
```

Alternatively, you can create and activate a virtual environment holding the
Hilde installation and all dependencies like this:

```
python3 -m venv venv
source venv/bin/activate
cat requirements.txt | xargs -n 1 -L 1 pip install
pip install .
```

**Settings Files**

`hilde` uses the Python `configparser` module for parsing settings files named
`settings.in` and the configuration file `hilde.cfg`. The
parser is augmented by `JSON` so it understands any input on the right hand side that is
valid `JSON`. The inputs get converted to Python objects according to [this conversion
table](https://realpython.com/python-json/#serializing-json).

**New Features**
* Simplified Settings Files:
  * Settings files named `settings.in` are automatically parsed when calling
    `Settings()` within Hilde.
  * The configuration file `hilde.cfg` gets installed to system.
* Molecular dynamics workflow with input and output files
  * see hilde/examples/md
* Phonopy workflow with input and output files
  * see hilde/examples/phonopy
* Relaxation workflow with config file and output files
  * see hilde/examples/relaxation
* YAML Trajectories:
  * save MD trajectories as YAML with tools in `hilde.trajectories`
  * example in `hilde/examples/trajectory/trajectory.son.ipynb`
* Emails:
  * send notifications via email with `hilde.helpers.notifications.send_simple_mail`
* Watchdogs:
  * supervise e.g. an MD to estimate when the walltime will be reached.
    Example in `examples/md/md_with_watchdog.ipynb`
* Wrapper for `phono3py`
  * Preprocess and re-creation of Phono3py objects from precomputed force
  constants, see examples
* Wrapper for `phonopy`
  * Preprocess and (some) postprocess, see examples
* Templates
  * `from hilde.templates.lammps import setup_lammps_si` to provide lammps calculator
* Brillouin zone helpers
  * `hilde.helpers.brillouinzone` features `get_paths`, `get_bands`, and
  `get_labels` to provide paths in the BZ that can be fed to `phonopy` via
  `phonon.set_bandstructure(bands)`, and
  `phonon.plot_band_structure(labels=labels)`.
  * These functions are used by `hilde.phonopy.plot_dos_and_bandstructure` to
  plot DOS and bandstructure in the working directory.
* Scripts:
  * `make_supercell`: create supercell from supercell matrix or
  target target
  * `geometry_info`: print geometry information for given input
  structure
* Symmetry Block Generation Functions
  * `AtomsInput`: A storage class that stores relevant information about a structure
  * `write_sym_constraints_geo`: Read any geometry.in file and use the list of `AtomInputs`
  to create a new supercell with a user defined symmetry block added to it
* FireWorks integration
  * Functions that can be used with PyTask to use FireWorks as a job manager
  * Jobs can now be submitted to the queue from a local machine and have the results processed locally


**Setup of FireWorks on Computational Resources**

See also: `doc/README_FHI_FireWorksConnections.md`
* Overview of Managing FireWorks Remotely
  * FireWorks does not copy functions but only finds them in the PYTHONPATH
  * To pass it functions give it the function_module.function_name as a str
  * Functions that are run on the local machine
    * All functions/files that set up FireWorks
      * All scripts that initially call hilde.tasks.fireworks.generate_firework
      * .cfg Files that define the steps (if used)
      * All functions used by a Fireworks without a task that calls a function in task2queue list
    * claunch_hilde and associated functions
  * Function that are run on the remote machine
    * All functions used by a Firework with a task that calls a function in task2queue
    * qluanch_hilde and associated functions
  * Functions that can run on both machines
    * All FireWorks API functions
    * All database accessors functions
    * Spec modifying functions (hilde.tasks.fireworks.fw_action_outs)
    * hilde.tasks.fireworks.generate_firework
  * Machine specific settings such as the aims_command is handled dynamically
    * It automatically changes when called on a machine
    * Can always use local settings without an issue
* Prerequisites for using FireWorks
  * Fabric 2 (for remote connections)
  * paramiko (used by Fabric 2)
  * python-gssapi (for gss authorization)
  * pymongo
* Using FireWorks on the clusters
  * Download/clone from https://github.com/materialsproject/fireworks.git and move the FireWorks directory
  * Modify fw\_tutorials/worker/my\_fworker.yaml and copy it to $HOME/.fireworks
    * Probably do not need to do any modifications if running on similar environments
    * Useful if you want to run specific jobs on specific machines without specified reservations
  * Modify fw\_tutorials/worker/my\_launchpad.yaml and copy it to $HOME/.fireworks
    * host: Host to the DB server
      * If connected through an ssh tunnel use localhost
    * port: Port the DB server is listening on
      * If connected through an ssh tunnel use the port connected the DB server via the tunnel
    * username: username used to access the database
    * password: password used to access the database
    * logdir: default directory to store logs
    * strm_lvl: How much information the launchpad prints by default
  * Modify the correct fw\_tutorials/queue\_???.yaml file for your submission system and copy it to $HOME/.fireworks/my\_qadapter.yaml
    * Only used on clusters
    * Set to minimal queue defaults
      * nodes = 1
      * ntasks_per_node = 32
      * walltime = "00:30:00"
      * queue = "express"
      * logdir = /some/path/that/must/exist (make sure this exists)
  * Find the FireWorks install directory with lpad version and modify
    $FW_INSTALL_DIR/fireworks/fw_config.py:
    * LAUNCHPAD_LOC: $HOME/.fireworks/my_launchpad.yaml
    * FWORKER_LOC: $HOME/.fireworks/my_fworker.yaml
    * QUEUEADAPTER_LOC: $HOME/.fireworks/my_qadapter.yaml
* Setup a MongoDB database for fireworks
  * Best to have it always accessible by all machines that need it
  * Check with the cluster management on what solution they'd prefer
* Connections between computers
  * Passwordless connections are preferred
  * If this is not possible you can pass the password as a command line argument, (delete
    bash history afterwards)
* FireWorks Etiquette
  * Name all Fireworks/WorkFlows
  * If you are using a shared launchpad only use lpad reset if everyone is okay with that

