jeertmans / differt Goto Github PK

View Code? Open in Web Editor NEW

1.0 2.0 1.0 1.69 MB

Differentiable Ray Tracing Toolbox for Radio Propagation Simulations

Home Page: https://differt.eertmans.be

License: MIT License

Python 71.15% Rust 28.85%

differentiable-simulations radio-propagation raytracing

differt's Introduction

DiffeRT

Usage

Warning

Until this package reaches version 0.1.x, breaking changes should be expected. Checkout the ROADMAP for future features.

If you have any suggestion regarding the development of this package, please open an issue.

The easiest way to install DiffeRT is through pip:

pip install differt

We provide pre-built binaries for most platforms. If you want (or need) to build the package from the source distribution, check out the requirements below.

Contributing

Important

The current documentation is very light and a more complete guide for new contributors will be written in the near future.

Until then, do not hesitate to reach me for help with GitHub issues!

This project is built using both Python and Rust code, to provide an easy-to-use but performant program. It also heavily uses the capabilities brought by JAX for numerical arrays.

Requirements

To run build this package locally, you need:

Python 3.9 or above;
Rust stable toolchain;
make (e.g., GNU Make or Make for Windows);
Maturin for building Python bindings from Rust code;
and Rye to manage this project.

Local development

The following commands assume that you installed the project locally with:

rye sync

and that you activated the corresponding Python virtual environment:

. .venv/bin/activate  # or .venv\Scripts\activate on Windows

Documentation

To generate the documentation, please run the following:

cd docs
make html

Finally, you can open build/html/index.html to see the generated docs.

Testing

Both Rust and Python codebases have their own tests and benchmarks.

Testing Rust code

You can very easily test you code using Cargo:

cargo test

or benchmark it:

cargo bench

Testing Python code

in the same way, you can very test you code with Pytest:

pytest

or benchmark it:

pytest --benchmark-only

differt's People

Contributors

Stargazers

Watchers

Forkers

spencerx

differt's Issues

Idea: optimizing wheels with PGO

This feature suggestion is highly inspired from maciejhirsz/logos#374, from a repository I maintain.

Actually, the idea would be to follow what pydantic-core does, see https://github.com/pydantic/pydantic-core/blob/44621f1dee5160c737a0749d21e0b2118fa99705/.github/workflows/ci.yml#L464-L557, to generate more performant code.

The setup for DiffeRT should be as follows:

Install the necessary LLVM tools:

rustup component add llvm-tools-preview

Compile code so that it can generate profiles:

RUSTFLAGS='-Cprofile-generate=/tmp/pgo-data/profdata' maturin build --release --out pgo-wheel

Install the library from new wheels:

pdm run python -m pip install differt --no-index --no-deps --find-links pgo-wheel --force-reinstall

Actually generate profiles by running code that uses wheels:

pdm run pytest --benchmark-only tests

Merge profiles. The actual path to llvm-profdata may change, see https://doc.rust-lang.org/rustc/profile-guided-optimization.html.

~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/bin/llvm-profdata merge -o /tmp/pgo-data/merged.profdata /tmp/pgo-data/profdata

Generate optimized build:

RUSTFLAGS='-Cprofile-use=/tmp/pgo-data/merged.profdata' maturin build --release --out dist

The only question I have is whether this is actually useful (did run a benchmark after, but not improvement noticed). I might need to write better benchmarks (that target actually what I want to optimize).

Bug - `all_paths*` methods from `differt.rt.graph` do not allow `from_` to be a keyword argument

E.g., DiGraph.all_paths(from_=0, ...) does not work as the text signature (from_) differs from the true signature (from). This is an issue because from cannot be used in Python.

Possible solutions:

Create a wrapper in Python that maps keyword-arguments to positional arguments.
Make from_ and others explicitly positional-only parameters.
Rename from to from_ inside Rust code (at least in the function signatures).

Add MRSV and check it in CI

Currently, we do not provide a minimum Rust supported version. We should provide such a version and add CI tests to check that it can compile with that version.