Skip to content

Latest commit

 

History

History
114 lines (73 loc) · 4.64 KB

README.md

File metadata and controls

114 lines (73 loc) · 4.64 KB
Raw

lammps-sys

License Documentation Crates.io Version

Builds and generates Rust bindings for the C interface of LAMMPS, the Large-scale Atomic/Molecular Massively Parallel Simulator.

Usage

lammps-sys is available on crates.io! (actually seriously this time).

[dependencies]
lammps-sys = "0.6.0"

Docs

See LAMMPS' library.cpp. This is the file that bindings will be generated to.

If you just want to see the rust signatures for the bindings, you can also generate those yourself:

git clone https://github.com/ExpHP/lammps-sys
cd lammps-sys
git submodule update --init
cargo doc --open

Modes of operation

lammps-sys will first probe for a system liblammps using pkg-config, and, failing that, will build it from source. This behavior may also be configured through the RUST_LAMMPS_SOURCE environment variable.

See the following documents for additional information:

Linking a system library

See Linking a system LAMMPS library.

Building from source

See Automatically building LAMMPS from source.

Configuration

Environment variables

The following environment variables are used by lammps-sys to control the build:

  • RUST_LAMMPS_SOURCE
    • RUST_LAMMPS_SOURCE=auto: Try to link a system library, else build from source. (default)
    • RUST_LAMMPS_SOURCE=system: Always link the system lammps library (else report an error explaining why this failed)
    • RUST_LAMMPS_SOURCE=build: Always build from source

Cargo features

exceptions

Enables the following API functions by ensuring that LAMMPS_EXCEPTIONS is defined:

lammps_has_error
lammps_get_last_error_message

The system library will be skipped if it was not built with the definition.

Optional packages

There are a number of cargo features named with the prefix package-. These are in one-to-one correspondence with LAMMPS' optional features documented here. Activating the feature "package-user-misc" corresponds to supplying the cmake file with -DPKG_USER-MISC=yes, which in turn has a similar effect to running make yes-user-misc if you were to use Lammps' classic make-based build system.

You should activate features for all of the packages used directly by your crate. Unfortunately, these currently only have an effect when building LAMMPS from source (see the cautionary discussion about packages in Linking a system LAMMPS library).

Be aware that these flags are almost entirely untested, and it's possible that some of them are unusable or even produce invalid cmake flags. Please file bug reports!

Some packages such as POEMS or REAX have additional library components that must be built. lammps-sys currently does not have any special handling for these, assuming that the cmake flags take care of this. If they work for you, that's great! If not, please file an issue.

Does it work?

For an easier time diagnosing building/linking issues, you can clone this repo and try running the link-test example.

$ git clone https://github.com/ExpHP/lammps-sys
$ cd lammps-sys
$ # note: submodule update is only needed when building lammps from source
$ git submodule update --init
$ cargo run --example=link-test
LAMMPS (31 Mar 2017)
Total wall time: 0:00:00

Be sure to try this using the environment variables and --features that you plan to enable in your own project.

License

Like Lammps, lammps-sys is licensed under the (full) GNU GPL v3.0. Please see the file COPYING for more details.

Release notes

See Release notes.

Citations

S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995)