Metadata-Version: 2.4
Name: DynaRef
Version: 6.10.0
Summary: Dyna: X-ray magnetic reflectivity simulation
Author-email: Stephane Grenier <stephane.grenier@neel.cnrs.fr>
License-Expression: GPL-2.0-or-later
Project-URL: Homepage, https://gitlab.com/dynadevgroup/Dyna
Project-URL: Documentation, https://pydyna.readthedocs.io
Project-URL: Changelog, https://gitlab.com/dynadevgroup/Dyna/-/blob/main/CHANGELOG.rst
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.22.4
Requires-Dist: scipy>=1.8.1
Requires-Dist: matplotlib>=3.5.2
Requires-Dist: PyQt5>=5.15.6
Requires-Dist: PyYAML>=6.0
Requires-Dist: pyobjc-framework-Cocoa>=10.0; sys_platform == "darwin"
Provides-Extra: dev
Requires-Dist: pytest>=8.2.5; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-env>=1.1.5; extra == "dev"
Requires-Dist: pytest-isolate>=0.0.13; extra == "dev"
Requires-Dist: pytest-qt>=4.4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Provides-Extra: macos
Requires-Dist: pyinstaller>=6.17; extra == "macos"
Dynamic: license-file

[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://gitlab.com/dynadevgroup/Dyna/-/graphs/main/charts)
[![made-with-python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)](https://www.python.org/)
[![GIT](https://img.shields.io/badge/development-GIT-green.svg)](https://gitlab.com/dynadevgroup/Dyna)
[![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-31010/)

This repository contains the Dyna development files.

"Dynamic x-ray reflectivity off- or on-resonant regime for isotropic,
 magnetic and anisotropic (multi)layer simulations and refinements Program"

<!-- ABOUT THE PROJECT -->
## About The Project

Dyna is a simulation program for reflectivity and transmittance of x-rays and optics, aimed at determining structural, magnetic and electronic stackings in ultrathin multilayers.

Among so many programs in the field, Dyna has several specificities : it includes anomalous, magnetic and anisotropic components in the index of refraction; it simulates reflectivities either versus angle, or versus x-ray energy, with arbitrary incident and out-going polarizations; it simulates Kerr and Faraday spectra, and transmittance through thin layers.

All the simulations can be simultaneously fitted against one model.

The program integrates a toolbox to create charge and magnetic factors from tables.

Dyna was also designed for pedagogical aims, making easy to slide parameters for on-the-fly effects.

Dyna is an on-going free and open-source project, under Python + Qt, or Matlab environments. Dyna can also be freely downloaded, and support is offered to users upon reasonable request.

Copyright Institut Neel, CNRS, Grenoble, France

### License

DynaRef is free software distributed under the GNU General Public License,
version 2 or (at your option) any later version (`GPL-2.0-or-later`). You may
use, study, modify, redistribute, and sell copies of DynaRef. If you distribute
a modified or combined version, you must keep it under GPL-compatible terms
and make the corresponding source code available to its recipients. Private
use and private modifications do not, by themselves, require publication.

This license is compatible with the GPL edition of PyQt5 used by DynaRef. See
[`LICENSE.txt`](LICENSE.txt) for the complete terms.

### Project Collaborators:

* Stéphane Grenier, stephane.grenier@neel.cnrs.fr
* Emmanuelle Jal (PhD, 2010-2013) now at LCPMR CNRS, Paris https://lcpmr.cnrs.fr/content/emmanuelle-jal              
* Valentin Chardonnet (PhD) - Emmanuelle Jal's group (LCPMR, Sorbonne Université, Paris)
* Diego Turenne (PhD) - (LCPMR, Sorbonne Université, Paris) diego.turenne@sorbonne-universite.fr
* Nicolas Jaouen Sextants beamline, Synchrotron Soleil, nicolas.jaouen@synchrotron-soleil.fr 
* Jean-Marc Tonnerre, jean-marc.tonnerre@neel.cnrs.fr
* Marta Elzo (PhD, 2009-2012)
* Ingrid Hallsteinsen - Padraic Shaffer’s group - Berkeley Nat. Lab.
* Daniel Schick Max-Born-Institute for nonlinear optics and short pulse spectroscopy im Forschungsverbund Berlin e.V.

Questions to: 

Stéphane Grenier, stephane.grenier@neel.cnrs.fr

### Installation

```console
pip install DynaRef
```

DynaRef is the name of the package available from Pypi, the DynaRef package contains Dyna.
Just launch with:
```console
% dyna
```

For an isolated Conda environment built from conda-forge dependencies:

```console
git clone https://gitlab.com/dynadevgroup/Dyna
cd Dyna
conda env create -f environment.yml
conda activate dyna
dyna
```

The candidate `dynaref` conda-forge recipe is prepared under
[`packaging/conda`](packaging/conda) and is exercised by the GitLab pipeline
while its staged-recipes submission is pending.

On macOS, a native `Dyna.app` bundle with the correct application name can
be built using the instructions in
[`docs/installation.rst`](docs/installation.rst#native-macos-application).
### Development install

```console
git clone https://gitlab.com/dynadevgroup/Dyna
cd Dyna
pip install -e .
dyna
```

### Python API

Dyna calculations can run without starting the Qt interface:

```python
from dyna import (
    Experiment,
    Formalism,
    ScanSettings,
    load_builtin_sample,
    run_reflectivity,
)

experiment = Experiment()
experiment.Formalism = Formalism.STEPANOV_ANGLE
experiment.angle = ScanSettings(0.1, 5.0, 0.01)
experiment.energy.start = 700.0

result = run_reflectivity(load_builtin_sample("w-si"), experiment)
print(result.x, result.intensity)
```

For reproducible batch calculations, use a JSON or YAML configuration such as
`examples/workflows/stepanov-angle.json` or
`examples/workflows/stepanov-angle.yaml`:

```console
dyna-sim examples/workflows/stepanov-angle.json --output reflectivity.csv
dyna-sim examples/workflows/stepanov-angle.yaml --output reflectivity.csv
dyna-sim examples/workflows/stepanov-angle.json --output reflectivity.npz
```

The same file can be used directly from Python:

```python
from dyna import load_config

result = load_config("examples/workflows/stepanov-angle.json").run()
result.save("reflectivity.csv")
```

Headless fitting is also available from JSON or YAML:

```console
dyna-sim fit examples/workflows/fit-angle.json --summary fit-summary.json --output fitted.csv
dyna-sim fit examples/workflows/fit-angle.yaml --summary fit-summary.json --output fitted.csv
```

More ready-to-adapt examples are available in `examples/README.md`.

The graphical interface can also save and load Dyna projects as YAML files.
This is the recommended project format for editable samples and experimental
parameters; legacy project files can still be loaded. The GUI also provides
sample-only YAML import/export actions for reusing the same layer stack across
several projects.

In the GUI, **Simulation Settings** selects only the scan type (angular or
energy), while the **Formalism** menu selects Parratt, the fast historical
Elzo or Stepanov solver, transverse Magnetic Parratt, CF2 anisotropic Parratt,
or an exact Berreman-Elzo/Berreman-Stepanov validation solver. A practical
workflow is to fit with the faster Elzo solver, use Stepanov for very thick or
numerically demanding stacks, and verify the final parameters with the
corresponding Berreman choice.
See [`docs/choosing-formalism.rst`](docs/choosing-formalism.rst) for a
decision-oriented comparison of the methods and their limitations.

Please cite both Dyna and the calculation method used in published work. The
Elzo, Stepanov, Berreman, and Parratt references are listed in
[`docs/references.rst`](docs/references.rst).
The anisotropic-stack validation also acknowledges pyGTM as an independent
numerical reference; its precise role and requested citations are documented
in [`docs/pygtm-validation.rst`](docs/pygtm-validation.rst).

Dyna also includes a small built-in YAML sample library:

```python
from dyna import list_samples, load_builtin_sample

print(list_samples())
sample = load_builtin_sample("w-si")
```

List or export those samples from the command line with `dyna-sim samples`.
The versioned YAML project and sample schema is documented in
[`docs/yaml-format.rst`](docs/yaml-format.rst).

### Features

* magnetic-sensitive susceptibility, arbitrary magnetic moment direction described by Euler angles, with the limitation of neglictible spin-orbit coupling in the valence states
* anisotropic susceptibility, in the limitation of an uniaxial symmetry along the depth of the film, for the simulation of oriented molecules or orbitally ordered films (not in python code yet)
* structural and magnetic sensitive transmittance.
* Angular/Q scans
* Energy spectra at fix angle or fix Q
* Polarization Analysis, in and out
* Refinement in user-defined interval, with limits on parameters, and constrains between parameters
* Multifit : one system is refined by simultaneous simulations of various data (angle and energy scans, of any polarization, energy or angle configurations).
* Calculates Scattering Factors from Tables
* Calculates Kerr MO rotation and ellipticities, providing that the angles are small, validity to be checked case by case
* Scriptable

### Testing
Integration tests are to be found in the tests folder.
Testing is done with pytest, it needs packages listed in tests/requirements_tests.txt. Mainly : pytest, pytest-qt and pytest-env. 
To launch all integration tests first activate the Dyna's python environement and then in the terminal do:

    python -m pytest tests -q
These tests mimic common user actions on the interface in order to check a basic minimum viability. 
As not all functionality is available, some tests have been written but are set to be skipped. 

Documentations:

https://pydyna.readthedocs.io

The development backlog is maintained in [`TODO.md`](TODO.md).
