---
title: "Introduction to hlrhotrix"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to hlrhotrix}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.align = "center")
library(hlrhotrix)
library(ggplot2)
```

## What is an hl-rhotrix?

An **hl-rhotrix** (heartless rhotrix, or even-dimensional rhotrix) is a
mathematical structure introduced by Isere (2018) as a rhotrix from which
the central *heart* entry has been removed. Unlike classical (odd-dimensional)
rhotrices, hl-rhotrices have even cardinality and a rich symmetric structure.

The basal hl-rhotrix of dimension 2 has the rhomboidal form:

```
    a11
  a21  a12
    a22
```

where `a11`, `a22` lie on the **vertical axis** (diagonal) and `a21`, `a12`
are **symmetric entries**.

All operations follow the **Robust Multiplication Method (RMM)** of
Isere & Utoyo (2025).

---

## Creating hl-rhotrices

### Dimension 2

```{r}
R <- make_R2(a11 = 5, a21 = 3, a12 = 6, a22 = 2)
print(R)
```

### Dimension 4

The 4-dimensional hl-rhotrix decomposes into two R2 principal minors
(A21, A22) and one M2 minor matrix (M21) — see Theorem 3.1.

```{r}
# Example 3.2 of the manuscript
A <- make_R4(
  a11 = -2,
  a21 =  3, c11 = 4,  a12 = 1,
  a31 =  1, c21 = 2,  c12 = -1, a13 = 0,
  a32 =  1, c22 = 1,  a23 = 0,
  a33 =  3
)
print(A)
```

### Dimension 6

```{r}
R6 <- make_R6(
  a11=1, a21=2, c11=3, a12=4,
  a31=5, c21=6, a22=7, c12=8, a13=9,
  a41=2, c31=3, a32=4, a23=5, c13=6, a14=7,
  a42=1, c32=2, a33=3, c23=4, a24=5,
  a43=6, c33=7, a34=8, a44=9
)
print(R6)
```

---

## Determinant

The determinant decomposes as (Definition 3.3):

$$\det(R_n) = \det\!\Bigl(\prod_k A_{2k}\Bigr) \otimes \det\!\Bigl(\prod_l M_{2l}\Bigr)$$

The sign of the M2 block is $-1$ when there is exactly one M2 minor,
$+1$ otherwise (Definition 3.4).

```{r}
det_hl(R)    # -8   (Example 3.3)
det_hl(A)    # -36  (Example 3.2)
det_hl(R6)   # 15360
```

**Theorem 3.4**: swapping all symmetric entries negates the determinant.

```{r}
B <- make_R4(
  a11=-2, a21=1, c11=4, a12=3,
  a31=0, c21=-1, c12=2, a13=1,
  a32=0, c22=1, a23=1, a33=3
)
det_hl(B) == -det_hl(A)
```

---

## Adjoint

```{r}
adj_hl(R)
adj_hl(A)
```

---

## Inverse

```{r}
inv_hl(R)
inv_hl(A)
```

Verify $A \cdot A^{-1} = I$ on each R2 block:

```{r}
Ai <- inv_hl(A)
for (k in seq_along(A$A)) {
  Ak <- matrix(c(A$A[[k]]["diag","col1"], A$A[[k]]["sym","col1"],
                 A$A[[k]]["sym","col2"],  A$A[[k]]["diag","col2"]), nrow=2)
  Ik <- matrix(c(Ai$A[[k]]["diag","col1"], Ai$A[[k]]["sym","col1"],
                 Ai$A[[k]]["sym","col2"],  Ai$A[[k]]["diag","col2"]), nrow=2)
  cat(sprintf("Block A%d * inv(A)%d:\n", k, k))
  print(round(Ak %*% Ik, 8))
}
```

---

## Eigenvalues

For a 2-dimensional hl-rhotrix, the characteristic polynomial is
$\Delta(t) = t^2 + \mathrm{tr}(A)\,t + \det(A)$ (Definition 3.8).

```{r}
# Example 3.3
trace_hl(R)          # 7
char_poly_hl(R)      # t^2 + 7t - 8
eigenvalues_hl(R)    # -8 and 1
```

For higher dimensions, eigenvalues are computed per principal R2 minor:

```{r}
eigenvalues_hl_high(A)
eigenvalues_hl_high(R6)
```

---

## Full summary

```{r}
summary_hl(R)
```

---

## Rhomboidal layout (ggplot2)

`plot_rhombus_gg()` returns a `ggplot` object showing the rhomboidal
structure. Blue nodes/regions are principal R2 minors; amber nodes/regions
are M2 minor matrices.

```{r fig.width=4, fig.height=4.5}
plot_rhombus_gg(2, title = "hl-Rhotrix  (dim = 2)")
```

```{r fig.width=5, fig.height=5.5}
plot_rhombus_gg(4,
  title    = "hl-Rhotrix  (dim = 4)",
  subtitle = "Minors A21, A22 (R2) and M21 (M2)")
```

```{r fig.width=7, fig.height=7.5}
plot_rhombus_gg(6,
  title    = "hl-Rhotrix  (dim = 6)",
  subtitle = "Minors A21, A22, A23 (R2) and M21, M22, M23 (M2)")
```

The returned object integrates naturally with the ggplot2 ecosystem:

```{r eval=FALSE}
# Export for the manuscript (PDF, 300 dpi)
ggsave("fig_rhombus_dim4.pdf", plot_rhombus_gg(4),
       width = 10, height = 10, units = "cm", dpi = 300)

# Three-panel figure with patchwork
library(patchwork)
plot_rhombus_gg(2) + plot_rhombus_gg(4) + plot_rhombus_gg(6)

# Further customisation
plot_rhombus_gg(4) +
  theme(plot.background = element_rect(fill = "grey98", colour = NA))
```

---

## References

- Isere, A.O. (2018). Even Dimensional Rhotrix. *Notes on Number Theory
  and Discrete Mathematics*, 24(2), 125--133.
- Isere, A.O. & Utoyo, T.O. (2025). On robust multiplication method for
  higher even-dimensional rhotrices. *Notes on Number Theory and Discrete
  Mathematics*, 31(2), 340--360.
- Isere, A.O., Braimah, J.O. & Correa, F.M. (2025). Algebraic Analysis of
  hl-Rhotrix Operations and Invariants. *(submitted)*