# OctaveExcel 1.0.0

OctaveExcel is a Windows Excel add-in that exposes GNU Octave functions as worksheet functions.

```excel
=octavefn("airy",0,E29)
```

For workbooks using MATLAB Spreadsheet Link, a formula such as:

```excel
=@matlabfcn("airy",0,E29)
```

can often be converted to:

```excel
=@octavefn("airy",0,E29)
```

when the MATLAB and Octave function signatures are compatible.

## Requirements

- Microsoft Excel for Windows
- GNU Octave
- .NET 10 Desktop Runtime
- .NET 10 SDK only if building from source

OctaveExcel searches for `octave-cli.exe` in this order:

1. `OCTAVE_CLI` environment variable
2. `PATH`
3. GNU Octave installations under Program Files

## Installation

Close Excel before installing.

From a binary release package:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1
```

The installer detects 32-bit or 64-bit Microsoft 365/Click-to-Run Excel. If detection is not available, specify it explicitly:

```powershell
.\install.ps1 -Architecture x64
```

or:

```powershell
.\install.ps1 -Architecture x86
```

To uninstall:

```powershell
.\uninstall.ps1
```

## Worksheet functions

### `octavefn`

Calls an Octave function:

```excel
=octavefn("sqrt",9)
=octavefn("sin",PI()/2)
=octavefn("airy",0,E29)
=octavefn("besselj",0,1.5)
=octavefn("sum",A1:A20)
=octavefn("eig",A1:C3)
```

Arguments may be numeric scalars, text, Boolean values, or numeric Excel ranges. Numeric ranges are passed to Octave as matrices.

### Diagnostics

```excel
=octaveversion()
=octavepath()
=octavestatus()
=octaveaddinversion()
=octavesyncmode()
=octavelogpath()
```

## Synchronous calculation

`octavefn()` is synchronous. Excel does not complete a calculation containing `octavefn()` until Octave returns a result or the call times out.

For VBA parameter sweeps, use an explicit calculation barrier before changing the next input:

```vb
Range("E29").Value = NewValue
Application.Calculate
Result = Range("F29").Value
```

The `Application.Calculate` call does not return until synchronous `octavefn()` formulas included in that calculation have finished.

An example is included in `examples\VBA_Synchronous_Calculation.bas`.

## Supported results

- Numeric scalars
- Numeric matrices
- Logical scalars and matrices
- Character strings
- Complex numeric results, returned as text such as `1.2-0.3i`

## Limitations

- Numeric ranges may contain numbers or blank cells. Blank cells are passed as zero.
- Only the first output from an Octave function is returned.
- Cell-array and struct results are not supported.
- Octave packages are not loaded automatically.
- Octave is started with `-qf`, so user and site startup files are not loaded.
- A worksheet call times out after 60 seconds.
- `octavefn()` blocks a set of common file, process, path, package, and evaluation functions. This is a convenience restriction, not a security sandbox.

## Building from source

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\build.ps1
```

The packed XLL files and end-user files are written to `dist`.

To create a distributable ZIP:

```powershell
.\make-release.ps1
```

## Diagnostics

The bridge log is stored at:

```text
%LOCALAPPDATA%\OctaveExcel\bridge.log
```

The log is limited to approximately 1 MB and retains one previous log as `bridge.log.1`.

To verify the Octave installation independently of Excel:

```powershell
.\test_octave.ps1
```
