---
title: "Working with big.matrix Objects"
author: "Frédéric Bertrand"
date: "`r format(Sys.Date())`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Working with big.matrix Objects}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(bigalgebra)
library(bigmemory)
```

## Overview

`bigalgebra` is designed to interoperate with the `bigmemory` ecosystem. This
vignette demonstrates how to create in-memory and file-backed `big.matrix`
objects, interact with them via the package's wrappers, and manage the
underlying resources safely.

## Creating in-memory `big.matrix` objects

In-memory matrices behave much like ordinary R matrices but reside in shared
memory, allowing multiple R sessions to access the same data.

```{r}
X <- big.matrix(3, 3, type = "double", init = 0)
X[,] <- matrix(1:9, nrow = 3)
X[]
```

Once created, the objects can be passed directly to Level 1 helpers:

```{r}
dvcal(ALPHA = 2, X = X, BETA = -1, Y = X)
X[]
```

## Working with file-backed matrices

File-backed matrices persist their contents on disk, making them suitable for
data sets that exceed available RAM.

```{r}
dir.create(tmp_fb <- tempfile())
Y <- filebacked.big.matrix(4, 2, type = "double",
                           backingpath = tmp_fb,
                           backingfile = "fb.bin",
                           descriptorfile = "fb.desc",
                           init = 0)
Y[,] <- matrix(runif(8), nrow = 4)
Y[]
```

These objects participate in higher-level operations without being loaded into
memory.

```{r}
Z <- filebacked.big.matrix(4, 2, type = "double",
                           backingpath = tmp_fb,
                           backingfile = "res.bin",
                           descriptorfile = "res.desc",
                           init = 0)
dvcal(ALPHA = 1.5, X = Y, BETA = 0, Y = Z)
Z[]
```

## Sharing matrices between sessions

The descriptor file records the metadata needed to reopen a file-backed matrix
in a new R session. The `attach.big.matrix()` helper reconstructs the object:

```{r}
Y_desc <- dget(file.path(tmp_fb, "fb.desc"))
Y_again <- attach.big.matrix(Y_desc)
identical(Y[,], Y_again[,])
```

Any operations performed via `bigalgebra` update the shared backing file,
allowing all attached references to observe the change.

```{r}
dsub(X = Z, Y = Y_again)
Y_again[]
```

## Cleaning up backing files

File-backed matrices allocate resources on disk. Deleting the backing and
descriptor files once they are no longer needed helps keep the workspace tidy.

```{r}
unlink(file.path(tmp_fb, c("fb.bin", "fb.desc", "res.bin", "res.desc")))
unlink(tmp_fb, recursive = TRUE)
```