Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
GiggleLiu committed Sep 24, 2023
1 parent 88b9e2b commit 846b354
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 17 deletions.
21 changes: 21 additions & 0 deletions CITATION.bib
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
@article{liu2021tropical,
title={Tropical tensor network for ground states of spin glasses},
author={Liu, Jin-Guo and Wang, Lei and Zhang, Pan},
journal={Physical Review Letters},
volume={126},
number={9},
pages={090506},
year={2021},
publisher={APS}
}

@article{liu2023computing,
title={Computing solution space properties of combinatorial optimization problems via generic tensor networks},
author={Liu, Jin-Guo and Gao, Xun and Cain, Madelyn and Lukin, Mikhail D and Wang, Sheng-Tao},
journal={SIAM Journal on Scientific Computing},
volume={45},
number={3},
pages={A1239--A1270},
year={2023},
publisher={SIAM}
}
37 changes: 20 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,33 @@
[![Build Status](https://github.com/TensorBFS/TropicalGEMM.jl/workflows/CI/badge.svg)](https://github.com/TensorBFS/TropicalGEMM.jl/actions)
[![codecov](https://codecov.io/gh/TensorBFS/TropicalGEMM.jl/branch/master/graph/badge.svg?token=8F6PH5Q9PL)](https://codecov.io/gh/TensorBFS/TropicalGEMM.jl)

The fastest tropical matrix multiplication in the world!
The fastest Tropical matrix multiplication in the world! Supported matrix element types include
* max-plus algebra: `Tropical{BlasType}`
* min-plus algebra numbers: `TropicalMinPlus{BlasType}`
* max-times algebra numbers: `TropicalMaxMul{BlasType}`

## See the discussion here

https://github.com/JuliaSIMD/LoopVectorization.jl/issues/201
Please check [`TropicalNumbers.jl`](https://github.com/TensorBFS/TropicalNumbers.jl) for the definitions of these types. The `BlasType` is the storage type, which could be one of `Bool, Float16, Float32, Float64, Int16, Int32, Int64, Int8, UInt16, UInt32, UInt64, UInt8, SIMDTypes.Bit`.

## Get started

Open a Julia REPL and type `]` to enter the `pkg>` mode, and then install related packages with
```julia
pkg> add TropicalNumbers, Octavian, TropicalGEMM, BenchmarkTools
pkg> add TropicalGEMM, BenchmarkTools, TropicalNumbers
```

In a julia REPL, you can try a minimum working example
Loading `TropicalGEMM` module into the workspace affects the `*` on Tropical matrices immediately. The following is a minimum working example
```julia
julia> using TropicalNumbers, Octavian, TropicalGEMM, BenchmarkTools
julia> using TropicalNumbers, BenchmarkTools

julia> a = Tropical.(randn(1000, 1000))
julia> a = Tropical.(randn(1000, 1000));

julia> @benchmark Octavian.matmul_serial($a, $a)
```
julia> @btime $a * $a;
2.588 s (6 allocations: 7.66 MiB)

**Warning:** using TropicalGEMM will overload the `mul!` function for Tropical numbers.
julia> using TropicalGEMM

julia> @btime $a * $a;
66.916 ms (2 allocations: 7.63 MiB)
```

## Benchmarks

Expand All @@ -35,8 +39,7 @@ The benchmark and plotting scripts could be found in the benchmarks folder.
![Float64](benchmarks/benchmark-float64.png)
![Float32](benchmarks/benchmark-float32.png)


## Warnings

It is expected to have an ambiguity error when one uses both `TropicalGEMM` and `CUDA`.
If you see these errors, please include `example/cudapatch.jl` in your project.
## References
1. This package originates from the following issue:
https://github.com/JuliaSIMD/LoopVectorization.jl/issues/201
2. For applications, please check the papers listed in the [CITATION.bib](/CITATION.bib).

0 comments on commit 846b354

Please sign in to comment.