User Guide: DCT Acceleration

Polyorder.jl includes a powerful DCT (Discrete Cosine Transform) Acceleration mode that significantly improves performance for simulations with mirror symmetry. For technical details, see DCT Acceleration.

Quick Start: Enabling DCT

The beauty of Polyorder's implementation is that DCT is enabled automatically when applicable. You generally do not need to change your code.

The solver detects if your system meets the requirements:

1. Symmetry: The Space Group supports Pure Mirror Planes (e.g., BCC Sphere Space Group 229 $Im\bar{3}m$, but NOT Gyroid $Ia\bar{3}d$).
2. Lattice: The Unit Cell is orthogonal (Cubic, Tetragonal, Orthorhombic).
3. Grid: The grid dimensions are even.

If these conditions are met, NoncyclicChainSCFT automatically switches to the optimized DCT solver.

# 1. Automatic Detection (Recommended)
# If 'w' has SG 229 (BCC Sphere) and cubic lattice, DCT is used automatically.
scft = NoncyclicChainSCFT(system, w; profile=:balanced)

# 2. Verifying DCT Usage
# usage: Check the internal solver type or log output
println(scft.solvers[1]) 
# Look for "OctAuxiliaryField" or check memory usage

Performance Impact

Memory Reduction

DCT operates on an Octant grid ($1/8^{th}$ of the volume). This reduces the temporary solver buffers (u, k², expw) by ~87.5%.

Application Examples

• BCC Spheres ($Im\bar{3}m$, SG 229): Fully supported.
• FCC Spheres ($Fm\bar{3}m$, SG 225): Fully supported.
• Lamellar ($Pmmm$, SG 47): Fully supported.
• Simple Cubic ($Pm\bar{3}m$, SG 221): Fully supported.

Note: Gyroid ($Ia\bar{3}d$, SG 230) is NOT supported by standard DCT-I because its symmetry involves glide planes (shifts), not just mirror reflections. Use FFT mode for Gyroid.

GPU Acceleration (VkDCT)

To enable the fastest possible DCT performance on GPU (via VkDCT), the following conditions must be met:

1. Hardware: Improved performance requires a CUDA-enabled GPU (NVIDIA).
2. Environment: You must have CUDA installed and loaded (using CUDA).
3. Dependencies: The specialized backend AcceleratedDCTs.jl must be version v0.4.0 or higher.
4. Backend Compilation:

   Due to the complexity of compiling customized GPU kernels, VkDCT is not shipped pre-compiled.

   You must clone AcceleratedDCTs.jl locally and compile the shared library manually:
   1. Clone AcceleratedDCTs.jl.
   2. Navigate to lib/VkDCT.
   3. Compile libvkfft_dct.so (refer to AcceleratedDCTs.jl documentation for details).

If these conditions are not met, Polyorder.jl may fall back to a slower generic implementation or CPU mode.

Troubleshooting

Why isn't DCT enabled?

If you expect DCT to be on but it isn't, check the following:

1. Check Space Group: Is your AuxiliaryField initialized with a compatible space group? ```julia

   Supported Cubic SGs: 221, 223, 225, 226, 229 (Not 230 Ia-3d)

   speciesym = Polyorder.symmetryspec(w) println(speciesym.outputis_octant) # Should be true if DCT maps are active ```

2. Check Grid Size: Are all dimensions even? julia size(w) == (32, 32, 32) # OK size(w) == (31, 31, 31) # NO - FFT will be used

3. Check Lattice: Is it orthogonal? julia Polyorder.orthogonal(w.lattice) # Should be Orthogonal()

4. Check Symmetry Enabled: DCT requires use_symmetry=true (or a symmetric profile).

   • Profiles like :balanced (default),:compact and :minimal use symmetry by default.
   • Profiles like :fast and :checkpoint DISABLE symmetry by default.
   • Fix: To use DCT with :checkpoint, you must enable symmetry explicitly:

   ```julia

   Use Checkpointing + DCT (Symmetry) -> effectively :minimal profile behavior

   scft = NoncyclicChainSCFT(system, w; profile=:checkpoint, symmetrize=true) ```

Explicitly Disabling DCT

If you need to force FFT mode (e.g., for debugging or cross-verification), you can explicitly disable it during construction:

# Force FFT mode even if system is compatible
scft = NoncyclicChainSCFT(system, w; use_dct=false)

Conversely, you can force it to fail if DCT standards are not met using use_dct=true:

# Will throw error if conditions (including symmetry) are not met
scft = NoncyclicChainSCFT(system, w; use_dct=true, symmetrize=true)