cnumpy for AutoHotkey v2

cnumpy is a native x64 numerical array library with a public C ABI and an AutoHotkey v2 facade. Its represented API is qualified against NumPy 1.25.0, including numerical results, error behavior, ownership, release ordering, and public-boundary performance.

This is an API projection, not a Python runtime or a claim that every NumPy argument and return category can cross the C/AutoHotkey boundary. The exact scope and intentional differences are documented in the NumPy 1.25 compatibility statement.

Qualified release

Item	Value
Platform	Windows x64
cnumpy version	1.21.0-cnumpy
NumPy oracle	1.25.0
AutoHotkey	v2, qualified with 2.1-alpha.30 x64
Release DLL	build/x64/Release/cnumpy_ahk.dll
SHA-256	7f0209ecfa291a4f291411e3a33f9c8e78e2aa14528f72488305c4d08260a3e0
Manifest	752/752 declarations owned; zero known gaps
Complete suites	Python 1,681; AutoHotkey 210; manifest/catalog 181

The hash identifies the final qualified binary. MSVC link-time code generation is not byte-reproducible for this project, so a source-identical local rebuild can have a different hash and must be requalified before being described as the same artifact.

Native AHK array conversion

NdArray.ToNativeArray() converts a numeric, C-contiguous cnumpy array into a real nested AutoHotkey Array without an element-level AHK loop. The interpreter layout is discovered at runtime and cross-validated by ahk/ahk_layout.ahk; the DLL fills the pre-built tree through cnp_ahk_fill_array_flat and cnp_ahk_fill_array_nd. No interpreter offsets are hardcoded and no machine code is embedded:

matrix := Numpy.Arange(0, 12).Reshape([3, 4])
native := matrix.ToNativeArray()
MsgBox native[2][3]     ; 6.0

Strided views raise ValueError; non-numeric dtypes raise TypeError. The result is a deep copy owned by AHK, so the source stays writable and independent. On this host, 1,000,000 float64 elements convert in ~5 ms (about 39x faster than ToArray()); a 1000x1000 matrix converts in ~12 ms. See benchmark/native_conversion_benchmark.ahk.

Quick start

For a guided, chapter-by-chapter introduction in the style of the NumPy Quickstart, read the bilingual tutorial site: English · 中文 (source in tutorial/, every example output verified against the qualified DLL by tutorial/verify_examples.ahk).

The root main.ahk is a complete sales-report application. Double-click it to process the bundled CSV and show the result or the original error in a Windows dialog; this mode does not require console stdout or stderr handles. For terminal automation, select the explicit headless interface:

$Ahk = 'C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe'
& $Ahk /ErrorStdOut=UTF-8 .\main.ahk --headless
& $Ahk /ErrorStdOut=UTF-8 .\main.ahk --headless `
  .\examples\data\sales.csv .\build\examples\custom-sales-report.csv

Headless failures preserve a nonzero process exit and write the real cnumpy exception to stderr. The two optional positional paths are input CSV and output CSV, in that order.

Set the DLL path before the first library call, release every NdArray, and call Numpy.Cleanup() last:

#Requires AutoHotkey v2.0
#Include ahk\numpy.ahk

Numpy.DllPath := A_ScriptDir "\build\x64\Release\cnumpy_ahk.dll"
Numpy.Init()
baseline := Numpy.AllocatedMemory()

source := 0
offsets := 0
shifted := 0
rowSums := 0
try {
    source := Numpy.Array([1, 2, 3, 4, 5, 6], [2, 3])
    offsets := Numpy.Array([10, 20, 30], [1, 3])
    shifted := Numpy.Add(source, offsets)
    rowSums := Numpy.Sum(shifted, 1)

    MsgBox shifted.ToString() "`nrow sums: " rowSums.ToString()
} finally {
    rowSums := 0
    shifted := 0
    offsets := 0
    source := 0
    retained := Numpy.AllocatedMemory()
    Numpy.Cleanup()
}

if retained != baseline
    throw Error("retained native memory: " (retained - baseline) " bytes")

The complete quickstart example also demonstrates a native shape error and prints deterministic output. The callback example covers the high-level callback facade and exception propagation. For end-to-end applications, use the practical examples: CSV sales analysis, ordinary least-squares regression, signal smoothing and spike localization, and a preallocated C pipeline.

Build

The supported build in this repository is the MSVC v143 x64 Release project. From PowerShell:

$MSBuild = 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\amd64\MSBuild.exe'
& $MSBuild src\cnumpy_ahk.vcxproj /m /t:Rebuild '/p:Configuration=Release;Platform=x64' /nologo /v:normal

The build writes the DLL and import library to build/x64/Release/. Compiler warnings remain visible and a nonzero build exit is a failure.

Run the examples and tests

Set $Ahk to a 64-bit AutoHotkey v2 executable:

$Ahk = 'C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe'
$Python = 'F:\Python\Python310\python.exe' # Python 3.10.11 with NumPy 1.25.0
& $Ahk /ErrorStdOut examples\ahk\quickstart.ahk
& $Ahk /ErrorStdOut examples\ahk\callbacks.ahk
.\examples\verify_ahk.ps1 -AhkPath $Ahk

& $Python -B -W error::ResourceWarning -m unittest discover -s benchmark\tests -v
& $Ahk /ErrorStdOut=UTF-8 ahk\numpy.test.ahk
& $Ahk /ErrorStdOut=UTF-8 benchmark\benchmark_smoke.test.ahk
& $Python benchmark\benchmark.py --profile focus --size-scale smoke --warmups 1 --samples 3 --target-sample-ms 1

Use the full benchmark protocol before making performance claims; a smoke run checks the pipeline, not regression stability. See the benchmark guide for profiles, timing boundaries, qualification metadata, and report interpretation. The host-scoped bilingual performance report publishes all 459 row-level results, both runtime orders, the stability diagnostic, limitations, and optimization priorities.

Documentation

• Quickstart tutorial site, English / 中文 (source: tutorial/)
• Getting started with AutoHotkey v2
• Practical, complete examples
• Bulk callbacks from AutoHotkey and C
• NumPy 1.25 compatibility and migration
• Final performance and behavior evidence
• Authoritative bilingual performance report
• Native conversion benchmark
• Public C API
• AutoHotkey/bulk callback ABI

Friendly Links

• MonoEven/stdlib-ahk
• Linux.do
• AutoHotkey Community Forum

Operating rules

• Treat returned arrays as owned unless an API explicitly documents a borrowed value. Release C owners with cnp_array_free/cnp_array_decref; release AHK owners by dropping every NdArray reference.
• Do not call Numpy.Cleanup() while arrays or callback results are live.
• Native failures are exceptions in the AHK facade and error states/statuses in C. They are not converted into empty arrays or substitute results.
• Prefer v2 exports where a legacy sentinel or scalar return loses NumPy meaning. The compatibility guide lists each important migration boundary.

License

cnumpy is available under the MIT License. Copyright (c) 2026 MonoEven. Third-party portions remain subject to the notices retained in their source files.