mars

KO | EN

gitlite — search

#editor #css #pdf #python #shell #linux #react #java #http #php

(★ 9)

MARS: Machine-Learned Force Field Framework for Automated Conformational Sampling, Vibrational Spectroscopy, and Microsolvation

파일 탐색기

ZIP 다운로드

- - docs.yml
  - test.yml
- - citation.md
  - license.md
- - conf_sampling.md
  - ensemble.md
  - flexibility.md
  - functional_groups.md
  - index.md
  - ir.md
  - log.md
  - mtd.md
  - optimizer.md
  - potentials.md
  - rmsd.md
  - solvation.md
  - solvents.md
  - topology.md
  - utils.md
  - viewer.md
- - conf_sample.gif
  - extra.css
  - favicon.ico
  - graphical_abstract.png
  - logo.png
- - conformer_search.md
  - ir.md
  - optimize.md
  - overview.md
  - solvation.md
  - viewer.md
- - conformer_search_section.md
  - constraints_section.md
  - ir_section.md
  - optimize_section.md
  - overview.md
  - solvation_section.md
- - alanine_dipeptide.md
  - conformer_search_recipes.md
  - index.md
  - ir_recipes.md
  - optimize_recipes.md
  - solvation_recipes.md
- - conformer_search.md
  - index.md
  - ir_spectroscopy.md
  - logging.md
  - nci_mode.md
  - optimization.md
  - potentials.md
  - solvation.md
- index.md
- install.md
- quickstart.md
- - 00_make_structure.py
  - 01_run_workflow.sh
  - alanine_dipeptide.xyz
  - best.xyz
  - conformers.xyz
  - ir_spectrum.dat
  - lowest_conformer.py
  - mode_analysis.txt
  - mtd_ensemble.xyz
  - normal_modes.xyz
  - optimized_structure.xyz
  - README.md
  - solvated.xyz
- - __init__.py
  - __main__.py
  - _common.py
  - _config.py
  - _conformer_search.py
  - _constraints.py
  - _ir.py
  - _optimize.py
  - _parser.py
  - _solvation.py
  - _viewer.py
- - __init__.py
  - manifest.toml
- __init__.py
- auto_config.py
- conf_sampling.py
- crossing.py
- ensemble.py
- flexibility.py
- functional_groups.py
- ir.py
- log.py
- mtd.py
- optimizer.py
- potentials.py
- rmsd.py
- sampling.py
- solvation.py
- spectro_constants.py
- topology.py
- utils.py
- utils_prune.py
- viewer.py
- benchmark.py
- conftest.py
- test_auto_config.py
- test_cli.py
- test_config.py
- test_crossing.py
- test_ensemble.py
- test_flexibility.py
- test_functional_groups.py
- test_ir.py
- test_log.py
- test_mtd.py
- test_optimizer.py
- test_potentials.py
- test_rmsd.py
- test_sampling.py
- test_solvation.py
- test_topology.py
- test_utils.py
- test_viewer.py
- regen_solvents.py
.gitignore
environment.yml
LICENSE
mkdocs.yml
pyproject.toml
README.md
setup.py

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> **M**achine-Learned Force Field Framework for **A**utomated
> Confo**r**mational **S**ampling, Vibrational Spectroscopy, and
> Microsolvation — JAX-native and GPU-accelerated.

[![Documentation](https://img.shields.io/badge/docs-tcpunilu.github.io%2Fmars-blue.svg)](https://tcpunilu.github.io/mars/)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![JAX](https://img.shields.io/badge/JAX-0.4.20+-orange.svg)](https://github.com/google/jax)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://raw.githubusercontent.com/TCPUniLU/mars/main/LICENSE)

MARS bundles three workflows that share a JAX backend, a pluggable
potential layer (SO3LR, MACE, dxtb, NCI, plus harmonic/LJ for testing),
and an automatic-configuration system:

- **Conformational sampling** — RMSD metadynamics + rotamer MD + optional
  genetic crossing, with MTD-only and MD-only variants
- **IR spectroscopy** — analytical Hessian (autodiff or finite differences)
  or MD-based dipole autocorrelation, with peak allocation to functional
  groups
- **Explicit solvation** — layer-by-layer shell construction with optional
  layerwise / global optimization, ~30 built-in solvents

---

## Install

Requires **Python ≥ 3.12**.

```bash
git clone https://github.com/TCPUniLU/mars.git
cd mars
pip install -e .            # CPU JAX; add the GPU wheel below
```

Pick the JAX backend for your hardware, then add the ML potential(s) you need:

```bash
pip install -U "jax[cuda12]"          # NVIDIA GPU (CUDA 12); or jax[cuda13], or plain jax for CPU

# SO3LR (default, recommended) — installed from source:
# v2 ships so3lr-s / so3lr-m / so3lr-l plus the legacy v1 model.
pip install -e ".[so3lr]"
git clone https://github.com/general-molecular-simulations/so3lr.git
cd so3lr && pip install . && cd ..
# pick a model at run time with --so3lr-model {so3lr-s,so3lr-m,so3lr-l,so3lr_v1}

pip install -e ".[mace]"              # MACE   (also: pip install mace-jax)
pip install "dxtb[libcint]>=0.4.0"    # dxtb (GFN-xTB); see the docs for the numpy note
```

Full instructions (GPU CUDA 12/13, the dxtb ↔ JAX NumPy conflict and how to
solve it, conda `environment.yml`, troubleshooting) are in the
[documentation](https://tcpunilu.github.io/mars/install/).

---

## First run

```bash
mars input.xyz --quick
```

That command auto-detects the topology, picks MTD parameters from the
molecular flexibility, runs an MTD + rotamer-MD sampling cycle, and
writes the unique low-energy conformers to `auto_final_ensemble.xyz`.

See the [Quickstart](https://tcpunilu.github.io/mars/quickstart/) for a
complete walkthrough with a methane XYZ.

---

## Documentation

| | |
|---|---|
| 📘 **[Documentation site](https://tcpunilu.github.io/mars/)** | Full docs, hosted on GitHub Pages |
| 🚀 [Quickstart](https://tcpunilu.github.io/mars/quickstart/) | 5-minute first run |
| 📚 [User guide](https://tcpunilu.github.io/mars/guide/) | Concepts for each tool |
| 🧪 [Examples](https://tcpunilu.github.io/mars/examples/) | Copy-pasteable recipes |
| ⚙️ [Config files](https://tcpunilu.github.io/mars/config/overview/) | TOML `--config FILE` reference |
| 💻 [CLI reference](https://tcpunilu.github.io/mars/cli/overview/) | Every flag, organized by subcommand |
| 🐍 [Python API](https://tcpunilu.github.io/mars/api/) | Auto-generated from docstrings |

The four subcommands at a glance:

```bash
mars input.xyz                            # conformational search (default)
mars ir input.xyz --plot                  # IR spectrum
mars optimize input.xyz --fmax 0.001      # local minimum
mars solvation solute.xyz --solvent water --padding 5.0
```

---

## Testing

```bash
pip install -e .[dev]
pytest -m "not requires_so3lr and not requires_mace and not requires_dxtb"
```

The harmonic-potential test suite runs in ~2 minutes on a single CPU
and needs no ML weights.

---

## Extending MARS — bring your own potential

MARS is **model-agnostic**: any energy model can be plugged in with a single
`@register_potential` decorator and used immediately via `--potential NAME`.

```python
from mars import register_potential, PotentialWrapper

@register_potential("my_potential")
class MyPotential(PotentialWrapper):
    def _build_energy_fn(self):
        def energy_fn(positions, **kwargs):
            ...   # return a scalar energy in eV
        return energy_fn
```

**We're happy to help you wire in your own force field / ML potential** —
neighbour lists, partial charges for IR, `vmap` batching, registration. Open an
issue or email us and we'll help (and happily link or upstream it). See the
[potentials guide](https://tcpunilu.github.io/mars/guide/potentials/).

---

## Citation

MARS is described in a preprint of the same title — please cite it:

```bibtex
@article{mars2026,
  title   = {MARS: Machine-Learned Force Field Framework for Automated Conformational Sampling, Vibrational Spectroscopy, and Microsolvation},
  author  = {Su{\'a}rez-Dou, Sergio and Gallegos, Miguel and Tkatchenko, Alexandre},
  journal = {ChemRxiv},
  year    = {2026},
  doi     = {10.26434/chemrxiv.15007087},
  note    = {Preprint}
}
```

For the full list of methods, ML potentials, and reference data to cite,
see the [Citation page](https://tcpunilu.github.io/mars/about/citation/).

---

## License

MIT License — see [LICENSE](LICENSE). Developed in the Theoretical Chemical
Physics group at the University of Luxembourg, supported by the ERC grant
FITMOL.

## Support & contact

Questions, bug reports, and help integrating a new potential are all welcome:

- Issues / discussions: <https://github.com/TCPUniLU/mars/issues>

mars

파일 탐색기

# CDN으로 사용하기

Was this content helpful?

Recent Feedback

Download README