1# 🐙 Poulpy-CPU-REF
 2
 3**Poulpy-CPU-REF** is the **reference (portable) CPU backend for Poulpy**.
 4
 5It implements the Poulpy HAL extension traits without requiring SIMD or specialized CPU instructions, making it suitable for:
 6
 7- all CPU architectures (`x86_64`, `aarch64`, `arm`, `riscv64`, …)
 8- development machines and CI runners
 9- environments without AVX or other advanced SIMD support
10
11This backend integrates transparently with:
12
13- `poulpy-hal`
14- `poulpy-core`
15- `poulpy-schemes`
16
17---
18
19## When is this backend used?
20
21`poulpy-cpu-ref` is always available and requires **no compilation flags and no CPU features**.
22
23It is automatically selected when:
24
25- the project does not request an optimized backend, or
26- the target CPU does not support the requested SIMD backend (e.g., AVX), or
27- portability and reproducibility are more important than raw performance.
28
29No additional configuration is required to use it.
30
31---
32
33## 🧪 Basic Usage
34
35```rust
36use poulpy_cpu_ref::FFT64Ref;
37use poulpy_hal::{api::ModuleNew, layouts::Module};
38
39let log_n: usize = 10;
40let module: Module<FFT64Ref> = Module::<FFT64Ref>::new(1 << log_n);
41```
42
43This works on **all supported platforms and architectures**.
44
45---
46
47## Performance Notes
48
49`poulpy-cpu-ref` prioritizes:
50
51* portability
52* correctness
53* ease of debugging
54
55For maximum performance on x86_64 CPUs with AVX2 + FMA support, consider enabling the optional optimized backend:
56
57```
58poulpy-cpu-avx (feature: enable-avx)
59```
60
61Benchmarks and applications can freely switch between backends without changing source code — backend selection can be handled with feature flags, for example
62
63```rust
64#[cfg(all(feature = "enable-avx", target_arch = "x86_64", target_feature = "avx2", target_feature = "fma"))]
65use poulpy_cpu_avx::FFT64Avx as BackendImpl;
66
67#[cfg(not(all(feature = "enable-avx", target_arch = "x86_64", target_feature = "avx2", target_feature = "fma")))]
68use poulpy_cpu_ref::FFT64Ref as BackendImpl;
69```
70
71---
72
73## 🤝 Contributors
74
75To implement your own backend (SIMD or accelerator):
76
771. Define a backend struct
782. Implement the open extension traits from `poulpy-hal/oep`
793. Implement the `Backend` trait
80
81Your backend will automatically integrate with:
82
83* `poulpy-hal`
84* `poulpy-core`
85* `poulpy-schemes`
86
87No modifications to those crates are necessary — the HAL provides the extension points.
88
89---
90
91For questions or guidance, feel free to open an issue or discussion in the repository.
92
93```