[RFC]: Provide APIs for computing Fast Fourier Transforms

[aryan7071]

Full name

Aryan kumar

University status

Yes

University name

Guru Gobind Singh Indraprastha University

University program

B.Tech

Expected graduation

2027

Short biography

My name is Aryan Kumar. I am a 3rd-year student at JIMS Engineering Management Technical Campus (India). My area of expertise is Full stack development along with backend in Node.js. My objective is to work as a software engineer. I've previously worked on MERN and MEAN projects, Image Recognition and AI based projects. I am a hard-working individual, honest and dedicated to my work, and always keen to acquire new skills. Outside of academics and work, I enjoy going to the gym, which helps me stay disciplined and energized. My flaw is that I may be affected mentally if I don't complete a task. I can't move to another issue until that is complete. However, I am addressing my shortcomings now by working on tasks together and sharing my time with different issues.

Timezone

Indian Standard Time (IST), UTC+5:30

Contact details

aryan002005@gmail.com

Platform

Windows

Editor

My preferred code editor is Visual Studio Code (VSCode). I prefer it because it is lightweight yet feature-rich, with excellent support for JavaScript, Node.js, and C/C++ through IntelliSense and extensions. The built-in Git integration and ESLint extension have been especially useful during my stdlib contributions, where strict linting standards are enforced. The integrated terminal also means I can run tests and build commands without switching windows, making my workflow smooth and efficient.

Programming experience

JavaScript was my first programming language, which I started learning in 10th grade. After finishing my 12th standard board exams, I started learning front-end development, and by the time I completed my 1st year of college, I had already covered full-stack development. After that, I participated in SIH (Smart India Hackathon) twice and qualified at the inter-college level, along with several other hackathons. During this period, I learnt a lot, which eventually led me to start my open-source journey. StdLib is my first open-source organisation.

JavaScript experience

I have been working with JavaScript since 10th grade, and it has been my primary language throughout my development journey from building front-end projects to full-stack MERN applications and backend APIs with Node.js. Through my stdlib contributions, I have also gained experience writing JavaScript that follows strict linting standards and works with typed arrays. My favorite feature of JavaScript is async/await, as it makes handling non-blocking operations clean and efficient. My least favorite feature is its type coercion behavior, where JavaScript silently converts types in unexpected ways and can lead to hard-to-track bugs, which is why I enjoy using TypeScript when possible.

Node.js experience

I have been working with Node.js for the past two years as my primary backend technology. I have used it extensively to build REST APIs, handle server-side logic, and manage database connections with MySQL and MongoDB in my MERN stack projects. Through my stdlib contributions, I have also gained experience with Node.js at a lower level, working with N-API bindings, native addons, and typed arrays which has deepened my understanding of how Node.js interacts with C-level code. This experience is directly relevant to this project, as the FFT native backend will be exposed to JavaScript through Node.js N-API bindings.

C/Fortran experience

I have working experience with C and C++ from my academic background and personal projects, and I am comfortable with core concepts like pointers, memory management, structs, and array operations. Through my stdlib contributions on the BLAS bindings issue (#2039) and the C implementations issue (#649), I have also gained hands-on experience writing C code that follows stdlib's conventions and integrates with N-API bindings. I have basic knowledge of Fortran I understand its syntax, subroutine structure, and how it handles arrays which I picked up while studying reference implementations in the stdlib codebase. This is sufficient for this project since the primary implementation will be based on pocketfft, a C++ library.

Interest in stdlib

What interests me most about stdlib is its goal of bringing serious numerical computing to JavaScript. The way stdlib maintains strict standards for testing, documentation, and code quality is something I truly admire and it has helped me become a better developer. My favorite feature is the ndarray the way it handles arrays with stride and offset support, similar to NumPy, is really clean and well designed. Beyond the code, the community is what keeps me engaged. The mentors are calm, patient, and always ready to help, which has made my first four months here a great learning experience.

Version control

Yes

Contributions to stdlib

Open Pull Requests

10798
10689
10606
10503
10498
10182
9866
9847
9841
#9695
#9656
#9635
#9627
#9624
#9610
#9525
#8926
#8630
#8607
#8562

Merged Pull requests

#10482
#10481
#9284
#9024
#9020
#9014
#9012
#9011
#9008
#9007
#8999
#8669
#8668
#8666
#8664
#8654

Closed Pull requests

#10544
#8534

Open issue

#112

stdlib showcase

I have created a dedicated repository at https://github.com/aryan7071/stdlib-use to explore and showcase stdlib's functionality. The repository contains the following demos:

math.js - explores stdlib's core math utilities and arithmetic functions
math-special.js - demonstrates the use of @stdlib/math/base/special functions including complex number operations
math-complex.js - showcases stdlib's complex number math functions operating on complex64 and complex128 types
ndarray.js - explores stdlib's ndarray API including creating arrays with custom strides and offsets, and performing operations on them
random.js - demonstrates stdlib's random number generation utilities

This hands-on exploration helped me deeply understand how stdlib packages are structured, how ndarrays handle stride and offset semantics, and how complex number types work internally all of which are directly relevant to implementing the FFT APIs proposed in this project.

Goals

My goal for this GSoC project is to implement a comprehensive set of Fast Fourier Transform (FFT) APIs for stdlib-js that stdlib users can actually use in their projects. The API will conform to the 2023.12 Array API specification and closely mirror NumPy's numpy.fft namespace.
An important thing to note about this project is that it is non-atomic. The FFT functions can be implemented and merged one by one as independent packages. Even if I only finish half the functions, those completed packages will be fully tested, documented, and immediately useful to stdlib users. This makes the project well-suited for incremental pull requests throughout the program rather than one large code dump at the end.
The project builds directly on top of PR #4121 by @gunjjoshi, which is porting the low-level FFTPACK compute routines to JavaScript. My project sits on top of that work and exposes the clean, user-facing API layer similar to how NumPy's numpy.fft sits on top of pocketfft internally. The 17 low-level packages in PR #4121 map directly to the high-level functions I will implement:

cfftf and cfftb → fft and ifft
cffti → initialisation used internally by fft and ifft
rfftf and rfftb → rfft and irfft
rffti → initialisation used internally by rfft and irfft
cosqf, cosqb, cosqi → dct (Type II) and idct
cost, costi → dct (Type I)
sinqf, sinqb, sinqi → dst (Type II) and idst
sint, sinti → dst (Type I)
decompose → internal utility used by all transforms

Architecture - hooking strided routines to top-level ndarrays:

Following the guidance from @kgryte to look at blas/ext, the implementation
will use the same three-layer architecture as @stdlib/blas/ext:

• Layer 1 the strided fftpack routines from PR #4121 (e.g.
  fft/base/fftpack/cfftf). These operate on a raw buffer with stride and
  offset, with no ndarray awareness. This mirrors @stdlib/blas/ext/base/dsum.

• Layer 2 ndarray wrappers I will author (e.g. fft/base/ndarray/cfft).
  These use @stdlib/ndarray/base/data-buffer, stride, offset, and numel
  to unwrap an ndarray and forward the raw arguments to the Layer 1 strided
  routine — exactly as blas/ext/base/ndarray/dsum calls
  blas/ext/base/dsum.

• Layer 3 top-level user-facing packages I will author (e.g. fft/fft).
  These handle dtype dispatch (complex128 vs complex64), default arguments,
  norm modes ('backward', 'ortho', 'forward'), and axis selection, then
  delegate to the Layer 2 ndarray wrapper — mirroring blas/ext/sum.

This layered design keeps the strided routines from PR #4121 independently
reusable at the base level, while the top-level packages expose a clean,
ndarray-aware API consistent with the rest of stdlib.

Packages by priority:
P1 Core (Array API spec, must deliver):

fft and ifft - 1-D complex FFT, calling cfftf and cfftb from fftpack
rfft and irfft - 1-D real FFT, calling rfftf and rfftb from fftpack
fftn and ifftn - N-D DFT over arbitrary axes
rfftn and irfftn - N-D real FFT
fftfreq and rfftfreq - frequency helper functions (pure arithmetic, no FFT compute)

P2 High priority:

fftshift and ifftshift - shift zero-frequency component to centre
next_fast_len - find optimal FFT size for padding
fft2, ifft2, rfft2, irfft2 - 2-D transforms (thin wrappers around fftn and rfftn)

P3 Medium priority:

hfft and ihfft — Hermitian FFT
dct and idct — Discrete Cosine Transform Types I–IV, calling cosqf, cosqb, cost, costi from fftpack
dst and idst — Discrete Sine Transform Types I–IV, calling sinqf, sinqb, sint, sinti from fftpack
dctn and idctn — N-D DCT
dstn and idstn — N-D DST

P4 Stretch goals (if time permits):

set_workers and get_workers , multi-threading support

Each package will be delivered as a complete, independently mergeable pull request following stdlib's BLAS interface conventions, with a pure JavaScript implementation as default, a high-performance native C++ backend powered by pocketfft via N-API bindings, full unit tests against NumPy reference fixtures, benchmarks, TypeScript declarations, REPL documentation, and stdlib-format API docs.

Note that some of these are more straightforward than others. For example, fftfreq involves only pure arithmetic with no FFT compute at all, while dct and dst require careful handling of four different transform types and their normalisation modes. It is also worth noting that the DCT and DST functions depend directly on the fftpack routines from PR #4121 being merged and stable if there are any delays there, I will prioritise completing all P1 and P2 packages first and come back to DCT/DST once the fftpack base is ready. The final product will still be very strong and immediately useful to stdlib users even without the DCT/DST packages.

I will also spend time fixing any bugs I encounter along the way, which is a natural part of working on a large codebase like stdlib. All work will include tests and documentation at every step, in line with stdlib's strict contribution standards.

References:

NumPy FFT documentation: https://numpy.org/doc/stable/reference/routines.fft.html
pocketfft repository: https://github.com/mreineck/pocketfft
PR #4121 (fft/base/fftpack): stdlib-js/stdlib#4121
PR #10354 (fft/base/fftpack/decompose): stdlib-js/stdlib#10354
Cooley, J. W., & Tukey, J. W. (1965). An algorithm for the machine calculation of complex Fourier series. Mathematics of Computation, 19(90), 297–301.

Why this project?

What excites me most about this project is that it sits right at the intersection of everything I have been working towards in stdlib C/C++ native backends, ndarray internals, and N-API bindings. FFT is a fundamental building block of scientific computing used in signal processing, image analysis, audio engineering, and physics simulations, and bringing that to JavaScript through stdlib means developers no longer have to leave the ecosystem to perform serious numerical work. Through my contributions to the BLAS bindings issue and C implementations issue, I have already worked with the exact patterns this project requires, and I am eager to take that experience further with a project of this scale.
What also excites me is the sheer technical depth and lasting impact of this work. Porting pocketfft, writing the extern "C" wrapper, and making it all work seamlessly with stdlib ndarrays is a genuinely challenging engineering task and that challenge is exactly what motivates me. With 29 functions spanning 1-D, 2-D, N-D, Hermitian, DCT/DST, and helper utilities, this project will lay a real and permanent foundation for scientific computing in JavaScript. I want to be the person who builds that foundation properly well tested, well documented, and built to stdlib's uncompromising standards.

Qualifications

On the technical side, I have hands-on experience with all the core skills this project requires. I have been writing JavaScript and Node.js for two years, and through my stdlib contributions on the BLAS bindings issue (#2039) and C implementations issue (#649), I have already written C code that integrates with stdlib's build system, follows its header conventions, and connects to JavaScript through N-API bindings the exact same pattern required for the FFT native backend. I also have a solid foundation in C/C++ from my academic background and have picked up basic Fortran while studying reference implementations in the stdlib codebase.

On the mathematical side, my Computer Science curriculum covered signals and systems, giving me a solid understanding of the Discrete Fourier Transform, normalisation modes, and conjugate symmetry. Combined with 4 months of active stdlib contributions across 35+ pull requests spanning Math, Statistics, ndarray, BLAS, float16, and Symbol packages, I have both the technical skills and codebase familiarity to execute this project successfully.

Prior art

FFT has been implemented across every major scientific computing ecosystem. The most directly relevant reference is NumPy (numpy.fft), which exposes the same API this project aims to mirror and is itself backed by pocketfft the same C++ library proposed as the native backend. SciPy (scipy.fft) extends this further with DCT, DST, and next_fast_len, and serves as the reference for the extended functions in this proposal. At the algorithm level, the foundational work is the Cooley-Tukey FFT algorithm (Cooley & Tukey, 1965), which reduces the DFT from O(n²) to O(n log n) and remains the basis of virtually all modern FFT implementations.
Within stdlib itself, there is already active work directly related to this project. PR #4121 by @gunjjoshi is a draft implementation of fft/base/fftpack that ports the classic FFTPACK library to JavaScript, adding 17 low-level compute packages. PR #10354 by @gunjjoshi adds the fft/base/fftpack/decompose package which is a fundamental building block for the FFT algorithm. This project builds directly on top of that low-level work by exposing the high-level, Array API-conforming user-facing interfaces on top of those compute routines. In the JavaScript ecosystem, existing solutions like fft.js on npm provide basic FFT functionality but lack ndarray integration and the comprehensive testing standards that stdlib demands.

Commitment

I plan to invest 30–35 hours per week during the GSoC period, with 6–7 hours on weekdays and 7–8 hours on weekends. During summer holidays, I will be able to push this up to 40 hours per week as I will have no college classes to attend. I have no employment during the GSoC period and I am completely dedicated to this project.
I have no plans to take any vacation during the GSoC term so that I can focus entirely on the project. Currently I attend around 40–48 hours of college per week, but with summer holidays during the GSoC period, I will be able to devote significantly more productive time to the project.
I intend to devote roughly 70% of my time to learning and coding and 30% to testing, documentation, and review. I will write a blog post every weekend to keep the community informed of my progress, contributions, and plan for the following week. I am also adaptive and willing to adjust my schedule according to the time zone of my mentors to ensure smooth and timely communication throughout the program

Schedule

week-by-week TimeLine

• Community Bonding Period:
  Study PR #4121 (fftpack) and PR #10354 (decompose) implementation thoroughly. Study stdlib BLAS interfaces to understand package structure and conventions. Set up development environment with Node.js, WSL, and build toolchain. Discuss final API surface and design decisions with mentors. Write design RFC and get mentor approval before coding begins.

• Week 1:
  Implement complete fft package pure JS implementation calling cfftf from fftpack, ndarray interface, unit tests against NumPy reference fixtures, benchmarks, REPL docs, and TypeScript declarations. Open pull request.

• Week 2:
  Implement complete ifft package pure JS implementation calling cfftb from fftpack, ndarray interface, unit tests, benchmarks, and docs. Write round-trip tests verifying fft followed by ifft recovers original signal. Open pull request.

• Week 3:
  Implement complete rfft package calling rfftf from fftpack and complete irfft package calling rfftb from fftpack. Unit tests, benchmarks, and docs for both. Open pull requests.

• Week 4:
  Implement complete fftfreq and rfftfreq packages (pure arithmetic helpers). Implement complete fftn package — N-D DFT over arbitrary axes using stride-aware ndarray iteration. Open pull requests.

• Week 5:
  Implement complete ifftn package. Implement complete rfftn and irfftn packages N-D real FFT. Unit tests, benchmarks, and docs for all. Open pull requests.

• Week 6 (midterm):
  Implement complete fftshift, ifftshift, and next_fast_len packages. Ensure all packages so far pass tests. Address all mentor review feedback. By this point P1 functions and most P2 functions will be complete and ready for evaluation. Open pull requests.

• Week 7:
  Implement complete fft2, ifft2, rfft2, and irfft2 packages as thin wrappers around fftn and rfftn. Implement complete hfft and ihfft packages. Open pull requests.

• Week 8:
  Wire up pocketfft C++ native backend vendor pocketfft_hdronly.h, write extern "C" wrapper, write N-API bindings (addon.c) for fft, ifft, rfft, irfft` using STDLIB_NAPI_ARGV macros. Wire up backend-switching dispatcher using tryRequire pattern similar to stdlib BLAS interfaces. Run cross-backend consistency tests.

• Week 9:
  Implement complete dct and idct packages (Types I–IV) calling cosqf, cosqb, cost, costi from fftpack. Unit tests comparing against SciPy reference values. Open pull requests.

• Week 10:
  Implement complete dst and idst packages (Types I–IV) calling sinqf, sinqb, sint, sinti from fftpack. Implement complete dctn, idctn, dstn, and idstn packages. Open pull requests.

• Week 11 (code freeze):
  Implement set_workers and get_workers packages if time permits. Write complete stdlib-format API docs for every package. Write NumPy-to-stdlib FFT migration guide. Run final benchmark suite across all packages and backends. Focus on completing all tests and documentation.

• Week 12:
  Address all remaining mentor feedback and open review comments. Fix any edge-case bugs discovered during final testing. Ensure all pull requests are clean and ready for merge.

• Final Week:
  Submit final code, complete documentation, and write a blog post summarising the project and all deliverables.

Related issues

• [Idea]: Provide APIs for computing Fast Fourier Transforms
• [RFC]: signal process related algorithms like fft family #3131
• feat: add initial implementation of fft/base/fftpack #4121 (Draft PR by @gunjjoshi)
• feat: add fft/base/fftpack/decompose #10354 (Open PR by @gunjjoshi)
• [RFC]: Add BLAS bindings and implementations for linear algebra (tracking issue) #2039
• [RFC]: Add C implementations to base special math functions (tracking issue) #649

Checklist

• I have read and understood the Code of Conduct.
• I have read and understood the application materials found in this repository.
• I understand that plagiarism will not be tolerated, and I have authored this application in my own words.
• I have read and understood the patch requirement which is necessary for my application to be considered for acceptance.
• I have read and understood the stdlib showcase requirement which is necessary for my application to be considered for acceptance.
• The issue name begins with [RFC]: and succinctly describes your proposal.
• I understand that, in order to apply to be a GSoC contributor, I must submit my final application to https://summerofcode.withgoogle.com/ before the submission deadline.

[aryan7071]

hi @kgryte
The 17 packages in PR #4121 map directly to these high-level functions I plan to implement:

• cfftf, cfftb → fft, ifft
• rfftf, rfftb → rfft, irfft
• cosqf, cosqb, cosqi → dct (Type II), idct
• cost, costi → dct (Type I)
• sinqf, sinqb, sinqi → dst (Type II), idst
• sint, sinti → dst (Type I)
• decompose → internal utility for all transforms

Beyond these, I have also researched other major libraries like NumPy, SciPy, and the Array API Standard, and found that the following functions are commonly supported and would be valuable to implement as part of this project:

• fftn, ifftn, rfftn, irfftn — N-D transforms
• fft2, ifft2, rfft2, irfft2 — 2-D wrappers
• fftfreq, rfftfreq, fftshift, ifftshift — helper utilities
• hfft, ihfft — Hermitian FFT
• dctn, idctn, dstn, idstn — N-D DCT/DST
• next_fast_len — optimal FFT size helper
• set_workers, get_workers — stretch goal

Could you please confirm if this is the right set of functions to implement for this project, or if there is anything I should add or remove?

Thank you!

[aryan7071]

Hi @kgryte we've already discussed this over on the zulip. You confirmed the function set and suggested using blas/ext as the architectural reference.

[gunjjoshi]

Hi @aryan7071, thanks for opening this issue. Here are a few initial thoughts from me:

1. The proposal can be more clear while stating which library handles computation on each path. The JS implementation builds on fftpack, while you mention under week 8 about introducing pocketfft as the native backend. You can state this more explicitly, regarding what will be the split, and why do we need 2 different libraries here.
2. In your week-wise timeline, some of weeks seem too overloaded. For instance, you plan to implement six complete packages (fft2, ifft2, rfft2, irfft2, hfft, ihfft) in week 7. Also, in weeks 9 and 10, you plan to work on eight DCT/DST packages in total, including types I–IV. Moreover, some of them such as DCT-IV doesn't seem to have a reference routine in fftpack, and you might need to do some more R&D in order to implement it. You may want to rescope each of these weeks.
3. Currently, you haven't mentioned how you'll be implementing packages such as hfft, ihfft. You can mention how you'll be implementing them or what reference you'll be using.
4. You plan to have a code-freeze in week 11, while also stating that you'll work on set_workers and get_workers in the same week. That seems contradicting.

Thanks.

[aryan7071]

@gunjjoshi, thank you for the detailed feedback! I have updated the proposal to address all four points:

1.I have added an explicit paragraph explaining the two-library split fftpack (PR #4121) handles all JS computation as it is already being ported to JavaScript by you and provides all the core routines this project needs. pocketfft handles the native backend as it is a single header-only file with no dependencies, has an MIT license, and is designed for high-performance use. Both produce identical results the native backend is purely an optional performance upgrade.

2. I have rescoped the overloaded weeks:

   • Week 7: fft2, ifft2, rfft2, irfft2 only
   • Week 8: hfft, ihfft + pocketfft native backend
   • Week 9: dct, idct Type I and II only
   • Week 10: dst, idst Type I and II + dctn, idctn
   • Week 11: dstn, idstn + full documentation pass
     Regarding DCT-IV I have added R&D on this to the community bonding period. DCT-IV will be implemented via reduction to DCT-II following SciPy's approach (phase pre/post-multiplication around the existing cosqf routine). If this proves too complex, it will be treated as a stretch goal.

3. I have added an explanation for hfft and ihfft they follow NumPy's approach. hfft(x) is implemented as irfft(conj(x)) since it operates on conjugate-symmetric input to produce real output, and ihfft(x) is implemented as conj(rfft(x)) / n. Both delegate to rfft and irfft implemented in Week 3, so no new fftpack routines are needed.

4. I have removed set_workers and get_workers from Week 11 completely and moved them to a true stretch goal after Week 12.

Thank you for taking the time to review