Skeleton/README.md

# Skeleton Framework

Skeleton is a computational library built with .NET 8.0, primarily designed to handle special complex matrices of small sizes (like 3x3) but supports matrices of any dimension over any custom field.  
Other modules such as morphisms, groups, rings, and fields are under development.

---

## Table of Contents

- [Features](#features)
- [Planned Features](#planned-features)
- [Supported Matrix Types](#supported-matrix-types)
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
    - [Example Usage](#example-usage)
    - [Simplifying with Aliases](#simplifying-with-aliases)
    - [Custom Dimension and Field](#custom-dimension-and-field)
        - [Custom Dimension](#custom-dimension)
        - [Custom Field](#custom-field)
- [License](#license)

---

## Features

- Vector and Matrix operations
- Vector spaces and Affine space operations
- Analytic functions, Polynomials, and Bivariant functions
- Sampling of Special Matrices
- Auto-registration for custom fields and dimensions

## Planned Features

- Statistics: Hypothesis testing
- Algebra: Group and Ring operations

## Supported Matrix Types

- General Matrix: `CategoryOf<IDim>.OnField<Complex>.FMatrix`
- Normal Matrix: `CategoryOf<IDim>.OnField<Complex>.FNormalMatrix`
- Diagonal Matrix: `CategoryOf<IDim>.OnField<Field>.FDiagonalMatrix`
- Unitary Matrix: `CategoryOf<IDim>.OnField<Complex>.FDiagonalMatrix`
- Special Unitary Matrix: `CategoryOf<IDim>.OnField<Complex>.FSpecialUnitaryMatrix`

**Note**: The types `CategoryOf<>.OnField<>.FLieUnitaryMatrix` and `CategoryOf<>.OnField<>.FSpecialLieUnitaryMatrix` may not represent matrices as their names imply. Instead, they denote congruence classes of \( \{ \log(x) \ | \ x \in SU \} \), where all eigenvalues lie within \((-\pi, \pi)\).  
Be cautious when using `FSpecialUnitaryMatrix.Log`, as this may not behave as the general logarithm function.

## Requirements

- .NET SDK version: 8.0.0

## Installation

Clone the repository:
```bash
git clone <repository_url>
cd Skeleton
dotnet restore
dotnet build
```
Alternatively, add the NuGet source:

```bash
dotnet nuget add source --name hangman-lab https://git.hangman-lab.top/api/packages/hzhang/nuget/index.json
dotnet add package --source hangman-lab Skeleton
```

## Usage

### Example Usage
You can use tensors (vectors and matrices) with predefined dimensions (e.g., 2, 3, 4) and predefined fields (e.g., double, complex):

```csharp

using Skeleton.Algebra.DimensionProviders;
using Skeleton.Algebra;
using System.Numerics;

var c2_1 = new CategoryOf<IDim2>.OnField<Complex>.FVector(1, 1);
var c2_2 = c2_1 * 0.5d;
var c2_3 = c2_1 + c2_2;

var m3_r = new CategoryOf<IDim3>.OnField<double>.FMatrix(
1d, 0d, 0d,
0d, 1d, 0d,
0d, 0d, 1d
);
```
### Simplifying with Aliases
Declare aliases in a Usings.cs file:

```csharp
global using C2 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim2>.OnField<System.Numerics.Complex>.FVector;
global using C3 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim3>.OnField<System.Numerics.Complex>.FVector;
global using C4 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim4>.OnField<System.Numerics.Complex>.FVector;

global using R2 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim2>.OnField<double>.FVector;
global using R3 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim3>.OnField<double>.FVector;
global using R4 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim4>.OnField<double>.FVector;

global using SU2 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim2>.FSpecialUnitaryMatrix;
global using SU3 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim3>.FSpecialUnitaryMatrix;
global using SU4 = Skeleton.Algebra.CategoryOf<Skeleton.Algebra.DimensionProviders.IDim4>.FSpecialUnitaryMatrix;

```
Then use the aliases in your code:
```csharp
C2 a = new C2(1, 0);
C2 b = a * 0.5d;

```
### Custom Dimension and Field
#### Custom Dimension
To define a custom dimension, declare an interface like this:
```csharp
using Skeleton.Algebra.DimensionProviders;
[OfDimension(10)]
public interface IDimX
{
    
}
```
#### Custom Field
To use a custom field, implement a FieldStructure class with the following required methods:
```csharp
[CustomFieldStructure]
class CustomFieldStructure : FieldStructure<TScalar>
{
    abstract TScalar Addition(TScalar self, TScalar other);
    abstract TScalar AdditionUnit { get; }
    abstract TScalar Multiplication(TScalar self, TScalar other);
    abstract TScalar MultiplicationUnit { get; }
    abstract TScalar AdditionInverse(TScalar self);
    abstract TScalar MultiplicationInverse(TScalar self);
    abstract TScalar Conj(TScalar self);
    abstract bool IsEqualApprox(TScalar self, TScalar other, double? absTol=null, double? relTol = null);
    abstract string RawCSharpRepresentation(TScalar x);
    abstract double MaxError(TScalar a);
    abstract TScalar SquareRoot(TScalar a);
    
}
```
Additionally, you can optionally implement the following methods for extended functionality:
```csharp
virtual TScalar Log(TScalar x);
virtual TScalar Exp(TScalar x);
virtual TScalar FromComplex(Complex a);
virtual TScalar RealMul(TScalar a, double b);
virtual Complex ComplexCast(TScalar a);
virtual TScalar Resolve(string dumpString);
virtual string DumpString(TScalar x);
virtual string RawPythonRepresentation(TScalar x);
virtual string RawRepresentation(TScalar x);
virtual TScalar FromReal(double x);
virtual double AsReal(TScalar x);
virtual TScalar Fix(TScalar x);
virtual TScalar Division(TScalar self, TScalar other);
virtual TScalar Subtraction(TScalar self, TScalar other);

```

## License
[MIT][license] © [hzhang][author]

<!-- Definitions -->
[author]: https://hangman-lab.top
[license]: license