mirror of
https://github.com/mihakralj/QuanTAlib.git
synced 2026-08-22 20:48:04 +00:00
Refactor documentation for clarity and detail
This commit is contained in:
Miha Kralj
@@ -1,69 +0,0 @@
|
||||
#!meta
|
||||
|
||||
{"kernelInfo":{"defaultKernelName":"csharp","items":[{"name":"csharp"},{"name":"fsharp","languageName":"F#","aliases":["f#","fs"]},{"name":"html","languageName":"HTML"},{"name":"http","languageName":"HTTP"},{"name":"javascript","languageName":"JavaScript","aliases":["js"]},{"name":"mermaid","languageName":"Mermaid"},{"name":"pwsh","languageName":"PowerShell","aliases":["powershell"]},{"name":"value"}]}}
|
||||
|
||||
#!markdown
|
||||
|
||||
# TValue Examples
|
||||
|
||||
This notebook demonstrates the usage of `TValue`, the fundamental data structure in QuanTAlib.
|
||||
|
||||
For detailed documentation, see [TValue.md](TValue.md).
|
||||
|
||||
#!csharp
|
||||
|
||||
// Reference the library
|
||||
#r "..\..\bin\QuanTAlib.dll"
|
||||
|
||||
using System;
|
||||
using QuanTAlib;
|
||||
|
||||
#!markdown
|
||||
|
||||
## Creating TValue
|
||||
|
||||
You can create a `TValue` using `DateTime` or `ticks`.
|
||||
|
||||
#!csharp
|
||||
|
||||
// Using DateTime
|
||||
var now = DateTime.UtcNow;
|
||||
var val1 = new TValue(now, 100.5);
|
||||
Console.WriteLine($"Created TValue: Time={val1.AsDateTime}, Value={val1.Value}");
|
||||
|
||||
// Using Ticks
|
||||
long ticks = now.AddMinutes(1).Ticks;
|
||||
var val2 = new TValue(ticks, 101.0);
|
||||
Console.WriteLine($"Created TValue: Time={val2.AsDateTime}, Value={val2.Value}");
|
||||
|
||||
#!markdown
|
||||
|
||||
## Implicit Conversions
|
||||
|
||||
`TValue` supports implicit conversions to `double` and `DateTime` for convenience.
|
||||
|
||||
#!csharp
|
||||
|
||||
double d = val1; // Implicitly gets Value
|
||||
DateTime t = val1; // Implicitly gets Time (as DateTime)
|
||||
|
||||
Console.WriteLine($"Double: {d}");
|
||||
Console.WriteLine($"DateTime: {t}");
|
||||
|
||||
// Arithmetic operations using implicit conversion
|
||||
double result = val1 + 5.0;
|
||||
Console.WriteLine($"Result (100.5 + 5.0): {result}");
|
||||
|
||||
#!markdown
|
||||
|
||||
## Immutability
|
||||
|
||||
`TValue` is immutable. You cannot change its properties after creation.
|
||||
|
||||
#!csharp
|
||||
|
||||
// val1.Value = 200; // Error: Property or indexer 'TValue.Value' cannot be assigned to -- it is read only
|
||||
|
||||
// To "change" a value, create a new instance
|
||||
var val3 = new TValue(val1.Time, 200.0);
|
||||
Console.WriteLine($"New TValue: {val3.Value}");
|
||||
+83
-21
@@ -1,37 +1,99 @@
|
||||
# TValue: Time-Value Pair
|
||||
|
||||
## Overview
|
||||
## What It Does
|
||||
|
||||
`TValue` is the fundamental building block of QuanTAlib. It represents a single data point in a time series, consisting of a timestamp and a double-precision floating-point value.
|
||||
`TValue` is the fundamental atomic unit of data in QuanTAlib. It represents a single point in a time series, consisting of a timestamp and a double-precision floating-point value. It serves as the standard input and output format for all indicators and data streams.
|
||||
|
||||
It is implemented as a lightweight `readonly struct` to ensure immutability and high performance (stack allocation, no GC overhead).
|
||||
## Design Philosophy
|
||||
|
||||
In high-frequency trading and quantitative analysis, memory allocation is a critical bottleneck. `TValue` is designed as a **lightweight, immutable struct** to ensure:
|
||||
|
||||
* **Zero Heap Allocation**: Being a struct, it lives on the stack or embedded in arrays, avoiding Garbage Collector (GC) pressure.
|
||||
* **Thread Safety**: Immutability guarantees safe concurrent access.
|
||||
* **Minimal Footprint**: Occupies exactly 16 bytes (8 bytes for `long` Time + 8 bytes for `double` Value), fitting efficiently in CPU cache lines.
|
||||
|
||||
## How It Works
|
||||
|
||||
`TValue` is implemented as a `readonly record struct`. It encapsulates:
|
||||
|
||||
* **Time**: A `long` representing ticks (UTC).
|
||||
* **Value**: A `double` representing the data magnitude.
|
||||
|
||||
It supports implicit conversions to `double` (extracting the value) and `DateTime` (extracting the time), making it syntactically fluid to use in calculations.
|
||||
|
||||
## Structure
|
||||
|
||||
### Definition
|
||||
|
||||
```csharp
|
||||
public readonly struct TValue
|
||||
{
|
||||
public readonly long Time; // Ticks (UTC)
|
||||
public readonly double Value; // Data value
|
||||
public readonly bool IsNew; // Metadata for streaming (optional usage)
|
||||
}
|
||||
public readonly record struct TValue(long Time, double Value);
|
||||
```
|
||||
|
||||
## Key Features
|
||||
### Properties
|
||||
|
||||
* **Lightweight**: 24 bytes (long + double + bool + padding).
|
||||
* **Immutable**: Thread-safe by design.
|
||||
* **Implicit Conversions**: Can be implicitly converted to `double` (returns Value) and `DateTime` (returns Time).
|
||||
* **Performance**: Designed for high-frequency trading and large dataset processing.
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `Time` | `long` | Timestamp in ticks (UTC). |
|
||||
| `Value` | `double` | The data value. |
|
||||
| `AsDateTime` | `DateTime` | Helper to view `Time` as a `DateTime` object. |
|
||||
|
||||
### Constructors
|
||||
|
||||
| Constructor | Description |
|
||||
|-------------|-------------|
|
||||
| `new TValue(long time, double value)` | Creates a TValue from raw ticks. |
|
||||
| `new TValue(DateTime time, double value)` | Creates a TValue from a DateTime object. |
|
||||
|
||||
## Usage
|
||||
|
||||
`TValue` is used throughout the library for:
|
||||
* Input to indicators (`Update(TValue)`).
|
||||
* Output from indicators (`Value` property).
|
||||
* Elements in `TSeries`.
|
||||
### Creating TValues
|
||||
|
||||
## Constructors
|
||||
```csharp
|
||||
// From DateTime
|
||||
var t1 = new TValue(DateTime.UtcNow, 100.5);
|
||||
|
||||
* `new TValue(long time, double value, bool isNew = true)`
|
||||
* `new TValue(DateTime time, double value, bool isNew = true)`
|
||||
// From Ticks
|
||||
var t2 = new TValue(DateTime.UtcNow.Ticks, 100.5);
|
||||
```
|
||||
|
||||
### Implicit Conversions
|
||||
|
||||
```csharp
|
||||
TValue tv = new TValue(DateTime.UtcNow, 42.0);
|
||||
|
||||
// Implicitly converts to double
|
||||
double val = tv; // 42.0
|
||||
|
||||
// Implicitly converts to DateTime
|
||||
DateTime dt = tv; // DateTime object
|
||||
```
|
||||
|
||||
### String Representation
|
||||
|
||||
```csharp
|
||||
Console.WriteLine(tv); // Output: "[2024-01-01 12:00:00, 42.00]"
|
||||
```
|
||||
|
||||
## Performance Profile
|
||||
|
||||
* **Memory**: 16 bytes per instance.
|
||||
* **Allocation**: 0 bytes (Stack allocated).
|
||||
* **Copying**: Cheap (fits in two 64-bit registers).
|
||||
|
||||
## Integration
|
||||
|
||||
`TValue` is the primary currency of the library:
|
||||
|
||||
* **Indicators**: `Update(TValue input)` accepts it.
|
||||
* **Series**: `TSeries` stores collections of it.
|
||||
* **Events**: `ITValuePublisher` broadcasts it.
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
* **SkipLocalsInit**: The struct is marked with `[SkipLocalsInit]` to suppress zero-initialization of locals, squeezing out nanoseconds in tight loops.
|
||||
* **AggressiveInlining**: All accessors and operators are inlined to ensure zero abstraction penalty.
|
||||
|
||||
## References
|
||||
|
||||
* [Structure of Arrays (SoA)](https://en.wikipedia.org/wiki/AOS_and_SOA)
|
||||
* [C# Struct Performance](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/struct)
|
||||
|
||||
Reference in New Issue
Block a user