4 releases
Uses old Rust 2015
0.6.0 | Aug 28, 2019 |
---|---|
0.5.2 | May 10, 2019 |
0.5.1 | Apr 9, 2019 |
0.5.0 | Apr 9, 2019 |
#531 in Science
35MB
683K
SLoC
lammps-sys
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)