Release 0.9.1

* Add installed `cmiclassirot` and `cmiclassirot-plot` user scripts to drive
  operation
* Implement clean and documented examples
* Performance improvements (Field)
* Implement sphinx/online documentation
* Start documenting the code and the module

.gitignore

@@ -1,3 +1,7 @@
 __pycache__
+build/
+doc/_build/
+doc/generated/
+public/
 *.egg-info
 *.h5

.gitlab-ci.yml

@@ -0,0 +1,22 @@
+image: python:3.11
+
+test:
+  stage: test
+  script:
+  - pip install -U sphinx
+  - pip install .
+  - sphinx-build -b html doc public
+  rules:
+    - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH
+
+pages:
+  stage: deploy
+  script:
+  - pip install -U sphinx
+  - pip install .
+  - sphinx-build -b html doc public
+  artifacts:
+    paths:
+    - public
+  rules:
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt

LICENSE.md

@@ -1,15 +1,21 @@
 # CMIclassirot licensing conditions
 
-CMIclassirot is provided by the CFEL Controlled Molecule Imaging group as is. It is licensed under
-the [GPL v3](./LICENSE-GPLv3.md) with the following additional requirements:
+CMIclassirot is provided by the CFEL Controlled Molecule Imaging group as is and without any
+warranty implied. It is licensed under the [GPL v3](./LICENSE-GPLv3.md) with the following
+additional requirements:
 
 * Its use for scientific work is acknowledged by the appropriate reference in any resulting work,
   e.g., scientific publication.
 
+  For current work, please cite the preprint Muhamed Amin, Jean-Michel Hartmann, Amit K. Samanta,
+  Jochen Küpper, ''Laser-induced alignment of nanoparticles and macromolecules for
+  single-particle-imaging applications'',
+  [arXiv:2306.05870 \[physics\]](https://arxiv.org/abs/2306.05870)
+
 * All corrections and enhancements must be contributed back to the development of the package within
   an appropriate time, i.e., no later than the publication of its first use.
-  Please create a pull request on GitHub (preferred) or send an appropriate patch against the latest
-  program version on the `develop` branch.
+
+  Please send us an appropriate patch against the latest program version on the `develop` branch.
 
 See the documentation for a full list of contributors.
 

README.devel.md

@@ -1,12 +1,22 @@
 # Development guidelines
 
-Please follow some simple rules for coding on CMIstark:
-- keep the code consistent across the whole package!
-- use git-flow (the tools and the concept)
-- consistently use two empty lines between functions/methods and three empty
+Please follow some simple rules for coding on CMIclassirot:
+
+* keep the code consistent across the whole package!
+* Document all code and adjust comments before you change the code to reflect
+  and discuss, even if only with yourself, the planned changes.
+* use git-flow (possibly the tools and especially the concept)
+* consistently use two empty lines between functions/methods and three empty
   lines above a class
 
 
+## Developer install
+
+You can install the project in _editable_ mode using
+```
+pip install --editable .
+```
+
 
 <!-- Put Emacs local variables into HTML comment
 Local Variables:

README.md

@@ -3,13 +3,34 @@
 Classical-mechanics simulations of the rotational dynamics of rigid molecules
 and nanoparticles in laser-electric fields.
 
-See the files in `examples/` for a start.
 
 ## Installation
 
+Change your working directory to the root directory of the package and run
+```
+pip install .
+```
+
+For development work `pip install --editable .` might be a useful alternative.
+
 
 ## Documentation
 
+See the inline documentation in the code or see the manual generated using `tbd`
+or[online at rtd](https://classirot.readthedocs.org).
+
+For a start, you can run the calculation inputs provided in `examples`:
+```
+cmiclassirot -o example.h5 <example>
+cmiclassirot-plot example.h5
+```
+
+See also [Release Notes.md] and [Contributors.md].
+
+For registered developers, updated [documentation of development
+versions](https://cmi.pages.desy.de/internal/software/cmiclassirot) is available
+at DESY.
+
 
 ## Citation
 
@@ -19,6 +40,8 @@ of nanoparticles and macromolecules for single-particle-imaging applications",
 [arXiv:2306.05870](https://arxiv.org/abs/2306.05870)
 
 
+
+
 <!-- Put Emacs local variables into HTML comment
 Local Variables:
 coding: utf-8

README.release.md

@@ -0,0 +1,49 @@
+# Release guidelines
+
+This recipe might need improvements, but keep the spirit in mind and update as
+appropriate.
+
+* Make sure all documentation and references are updated and all tests are
+  passed.
+* Update `Release Notes.md`.
+* Bump version (in setup.py and doc/conf.py) to reflect the new release
+* Copy current `develop` to `release`:
+```
+git checkout develop@{0}  # get working tree from "development", detach HEAD
+git reset --soft stable   # reposition detached HEAD on "stable"
+git commit                # enter the appropriate commit message
+git branch temp           # create a temporary branch "temp" at HEAD
+git checkout temp         # get on the new temporary branch
+git branch -M release     # rename "temp" to "stable"
+```
+* Tag the final release as vx.y or vx.y.z or, possibly, create a vx.y branch for
+  the release.
+* go back to develop `git checkout develop`
+* Set the version (in setup.py) to the next development-cycle version number,
+  e.g., `x.u-dev`.
+
+
+## Publish release version
+
+Push the release branch(es) and tag to github
+```
+git push github release
+git push github vx.y
+```
+
+
+## Create github release
+
+Go the the github project page and create a new release from the pushed tag
+vx.y.
+
+Provide a release title "Public release vx.y" and add the release notes from
+`Release Notes.md` as description of the github release.
+
+
+<!-- Put Emacs local variables into HTML comment
+Local Variables:
+coding: utf-8
+fill-column: 80
+End:
+-->

Release Notes.md

@@ -0,0 +1,26 @@
+# CMIclassirot release notes
+
+## Future Release(s) -- past 1.0
+
+* Provide $`\left<\cos^2\theta\right>(t)`$ trace in HDF5 files
+* Add examples for bionanoparticles
+
+
+## Release 0.9.2
+
+* Improve documentation
+
+
+## Release 0.9.1
+
+* Add installed `cmiclassirot` and `cmiclassirot-plot` user scripts to drive
+  operation
+* Implement clean and documented examples
+* Performance improvements (Field)
+* Implement sphinx/online documentation
+* Start documenting the code and the module
+
+
+## Release 0.9
+
+* Original functionality as described in arXiv:2306.05870

bin/cmiclassirot

@@ -0,0 +1,58 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; fill-column: 120 -*-
+#
+# This file is part of the CMIclassirot classical-rotation alignment simulations
+
+
+
+import click
+import time
+
+from cmiclassirot.propagate import Propagate
+
+
+@click.command() # help='Filename of definiton of Ensemble and Field',
+@click.argument('inputfilename',  required=1)
+@click.option('-o', '--output', 'output', default='cmiclassirot.h5', show_default=True,
+              help='Write output to specified filename.')
+@click.help_option('-h', '--help')
+def main(inputfilename, output):
+    """CMIclassirot driver program: calculate the time-evolution of rigid rotors in electric fields
+
+    This program reads an imputfile defining an Ensemble of Molecules and a Field and performs the calculation.
+
+    Besides the options defined below, the program requires the filename of the inputfile as the only positional
+    argument. The input must define the following Python variables, which are used in the calculation:
+
+    :class:`Ensemble` :param:`ensemble` Definition of the initial ensemble of molecules
+
+    :class:`Field` :param:`field` Definition of the time-dependet electric field
+
+    :param timerange: 2-tuple of initial and final time of integration
+
+    :param dt_save: Tiemstep for saving the :class:`Molecule`-positions to file
+
+    @author: Jochen Küpper <[email protected]>
+
+    """
+    # read specification of problem
+    with open(inputfilename, mode='r') as inputfile:
+        code = inputfile.read()
+    exec(code, globals())
+
+    # perform the computation
+    starttime = time.time()
+    print('Starting propagation of molecular dynamics')
+    p = Propagate(ensemble, field, timerange, dt_save)
+    print('  Propagation took', time.time()-starttime, 's')
+
+    # and save the results to the output file
+    starttime = time.time()
+    print('Saving data to file')
+    ensemble._save(output)
+    print('  Saving took', time.time()-starttime, 's')
+
+
+
+if __name__ == '__main__':
+    main()

bin/cmiclassirot-plot

@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+# -*- coding: utf-8; fill-column: 120 -*-
+#
+# This file is part of the CMIclassirot classical-rotation alignment simulations
+#
+# Plotting of degree of alignment and laser pulse
+
+from cmiclassirot.field import Field
+from cmiclassirot.sample import Ensemble
+import matplotlib.pyplot as plt
+import numpy as np
+import sys
+
+fname = sys.argv[1]
+
+e = Ensemble.FromFile(fname)
+print("Number of Molecules:", len(e.molecules))
+
+doa = np.zeros(len(e.molecules[0].pos))
+E = e.pulse
+
+for i in e.molecules:
+    t=[]
+    pulse = []
+    for j in range(len(i.pos)):
+        try:
+            doa[j] += i.pos[j].angle.rotation_matrix[2][2]**2
+            t.append(i.pos[j].time)
+            pulse.append(E(i.pos[j].time))
+        except:
+            pass
+doa = doa/len(e.molecules)
+
+fig, ax = plt.subplots(2)
+ax[0].plot(np.array(t)*1e9, doa)
+ax[1].plot(np.array(t)*1e9, Field.amplitude2intensity(np.array(pulse)) / (1e12 * 1e4))
+plt.xlabel('time (ns)')
+ax[0].set_ylabel(r'$\left<\cos^2\theta\right>$')
+ax[1].set_ylabel('$E$ ($10^{12}$~W/cm$^2$)')
+plt.tight_layout()
+plt.show()