xref: /libCEED/rust/libceed/README.md (revision 6eb0d8b4aff72517bac7a1ace48e04610a8fe084) 
1# libceed: efficient, extensible discretization
2
3[![GitHub Actions](https://github.com/CEED/libCEED/actions/workflows/rust-test-with-style.yml/badge.svg)](https://github.com/CEED/libCEED/actions/workflows/rust-test-with-style.yml)
4[![Documentation](https://docs.rs/libceed/badge.svg)](https://docs.rs/libceed)
5
6This crate provides an interface to [libCEED](https://libceed.org), which is a performance-portable library for extensible element-based discretization for partial differential equations and related computational problems.
7The formulation is algebraic and intended to be lightweight and easy to incorporate in higher level abstractions.
8See the [libCEED user manual](https://libceed.org) for details on [interface concepts](https://libceed.org/en/latest/libCEEDapi/) and extensive examples.
9
10![libCEED operator decomposition](https://libceed.org/en/latest/_images/libCEED.png)
11
12## Usage
13
14To call libCEED from a Rust package, the following `Cargo.toml` can be used.
15```toml
16[dependencies]
17libceed = "0.10.0"
18```
19
20For a development version of the libCEED Rust bindings, use the following `Cargo.toml`.
21```toml
22[dependencies]
23libceed = { git = "https://github.com/CEED/libCEED", branch = "main" }
24```
25
26```rust
27extern crate libceed;
28
29fn main() -> libceed::Result<()> {
30    let ceed = libceed::Ceed::init("/cpu/self/ref");
31    let xc = ceed.vector_from_slice(&[0., 0.5, 1.0])?;
32    let xs = xc.view()?;
33    assert_eq!(xs[..], [0., 0.5, 1.0]);
34    Ok(())
35}
36```
37
38This crate provides modules for each object, but they are usually created from the `Ceed` object as with the vector above.
39The resource string passed to `Ceed::init` is used to identify the "backend", which includes algorithmic strategies and hardware such as NVIDIA and AMD GPUs.
40See the [libCEED documentation](https://libceed.org/en/latest/gettingstarted/#backends) for more information on available backends.
41
42## Examples
43
44Examples of libCEED can be found in the [libCEED repository](https://github.com/CEED/libCEED) under the `examples/rust` directory.
45
46## Documentation
47
48This crate uses `katexit` to render equations in the documentation.
49To build the [documentation](https://docs.rs/libceed) locally with `katexit` enabled, use
50
51```bash
52cargo doc --features=katexit
53```
54
55## License: BSD-2-Clause
56
57## Contributing
58
59The `libceed` crate is developed within the [libCEED repository](https://github.com/CEED/libCEED).
60See the [contributing guidelines](https://libceed.org/en/latest/CONTRIBUTING/) for details.
61