### Install PureHDF Package

Source: https://github.com/apollo3zehn/purehdf/blob/dev/README.md

Use the .NET CLI to add the PureHDF package to your project.

```bash
dotnet add package PureHDF
```

--------------------------------

### Install Amazon S3 Package

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/amazon-s3.md

Use the .NET CLI to add the required package to your project.

```bash
dotnet add package PureHDF.VFD.AmazonS3
```

--------------------------------

### Configuring HDF5 Source Generator

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/intellisense.md

Example of setting up the H5SourceGenerator attribute to define the HDF5 file path for code generation and integrating it into the application.

```cs
using PureHDF;

[H5SourceGenerator(filePath: Program.FILE_PATH)]
internal partial class MyGeneratedH5Bindings {};

static class Program
{
    public const string FILE_PATH = "myFile.h5";

    static void Main()
    {
        using var h5File = H5File.OpenRead(FILE_PATH);
        var bindings = new MyGeneratedH5Bindings(h5File);
        var myDataset = bindings.group1.sub_dataset2;
    }
}
```

--------------------------------

### Installing PureHDF Source Generator

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/intellisense.md

Commands to add the PureHDF.SourceGenerator package to your project and restore dependencies.

```bash
dotnet add package PureHDF.SourceGenerator
dotnet restore
```

--------------------------------

### Accessing a Parent Group with Get()

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/intellisense.md

Illustrates how to retrieve a parent group object using the `Get()` method on the generated bindings, which is useful when not accessing a specific dataset.

```cs
var myGroup = bindings.group1.Get();
```

--------------------------------

### Parallel Reading with FileStream

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/concurrency.md

Demonstrates parallel data loading using FileStream, available starting with .NET 6. Requires .NET 6+ runtime.

```cs
const ulong TOTAL_ELEMENT_COUNT = xxx;
const ulong SEGMENT_COUNT = xxx;
const ulong SEGMENT_SIZE = TOTAL_ELEMENT_COUNT / SEGMENT_COUNT;

using var file = H5File.OpenRead(FILE_PATH);

var dataset = file.Dataset("xxx");
var buffer = new float[TOTAL_ELEMENT_COUNT];

Parallel.For(0, SEGMENT_COUNT, i =>
{
    var start = i * SEGMENT_SIZE;
    var partialBuffer = buffer.Slice(start, length: SEGMENT_SIZE);
    var fileSelection = new HyperslabSelection(start, block: SEGMENT_SIZE)

    dataset.Read<float>(partialBuffer, fileSelection);
});
```

--------------------------------

### Read 1D Datasets by Class

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/simple.md

Examples for reading various HDF5 data classes into C# arrays. Ensure the C# types match the underlying HDF5 data types.

```cs
// class: fixed-point

    var data = dataset.Read<int[]>();

// class: floating-point

    var data = dataset.Read<double[]>();

// class: string

    var data = dataset.Read<string[]>();

// class: bitfield

    [Flags]
    enum SystemStatus : ushort /* make sure the enum in HDF file is based on the same type */
    {
        MainValve_Open          = 0x0001,
        AuxValve_1_Open         = 0x0002,
        AuxValve_2_Open         = 0x0004,
        MainEngine_Ready        = 0x0008,
        FallbackEngine_Ready    = 0x0010
        // ...
    }

    var data = dataset.Read<SystemStatus[]>();
    var readyToLaunch = data[0].HasFlag(SystemStatus.MainValve_Open | SystemStatus.MainEngine_Ready);

// class: opaque

    var data = dataset.Read<MyOpaqueStruct[]>();

// class: compound

    /* option 1: faster (if no reference types are contained) */
    var data = dataset.Read<MyNonNullableStruct[]>();

    /* option 2: slower (useful to read unknown structs) */
    var data = dataset.Read<Dictionary<string, object>>();

// class: reference @ object reference

    var references = dataset.Read<NativeObjectReference1[]>();
    var firstRef = references.First();

    /* NOTE: Dereferencing would be quite fast if the object's name
     * was known. Instead, the library searches recursively for the  
     * object. Do not dereference using a parent (group) that contains
     * any circular soft links. Hard links are no problem.
     */

    /* option 1 (faster) */
    var firstObject = directParent.Get(firstRef);

    /* option 1 (slower, use if you don't know the objects parent) */
    var firstObject = root.Get(firstRef);

// class: reference @ region reference

    var references = dataset.Read<NativeRegionReference1[]>();
    var firstRef = references.First();
    var selection = root.Get(firstRef);
    var data = referencedDataset.Read<T>(fileSelection: selection);

// class: enumerated

    enum MyEnum : short /* make sure the enum in HDF file is based on the same type */
    {
        MyValue1 = 1,
        MyValue2 = 2,
        // ...
    }

    var data = dataset.Read<MyEnum[]>();

// class: variable length strings

    var data = dataset.Read<string[]>();

// class: variable length sequences

    var data = dataset.Read<T[][]>();

// class: array

    var data = dataset.Read<T[][]>;
```

--------------------------------

### Register Deflate (ISA-L) Filter in PureHDF

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/filters.md

Register the hardware-accelerated Deflate filter from Intel ISA-L. Install the PureHDF.Filters.Deflate.ISA-L package.

```csharp
using PureHDF.Filters;

H5Filter.Register(new DeflateISALFilter());
```

--------------------------------

### Create a HyperslabSelection

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/slicing.md

Hyperslab selections define blocks of data using start, stride, count, and block parameters.

```csharp
var fileSelection = new HyperslabSelection(start: 10, block: 50);
```

```csharp
var dataset = root.Dataset("myDataset");
var memoryDims = new ulong[] { 75, 25 };

var datasetSelection = new HyperslabSelection(
    rank: 3,
    starts: [2, 2, 0],
    strides: [5, 8, 2],
    counts: [5, 3, 2],
    blocks: [3, 5, 2]
);

var memorySelection = new HyperslabSelection(
    rank: 2,
    starts: [2, 1],
    strides: [35, 17],
    counts: [2, 1],
    blocks: [30, 15]
);

var result = dataset
    .Read<int[,]>(
        fileSelection: datasetSelection,
        memorySelection: memorySelection,
        memoryDims: memoryDims
    );
```

--------------------------------

### Register BZip2 (SharpZipLib) Filter in PureHDF

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/filters.md

This snippet registers the BZip2 filter using SharpZipLib. Install the PureHDF.Filters.BZip2.SharpZipLib package first.

```csharp
using PureHDF.Filters;

H5Filter.Register(new BZip2SharpZipLibFilter());
```

--------------------------------

### Register C-Blosc2 Filter

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/filters.md

Register the C-Blosc2 filter by installing the nuget package and instantiating the filter class. This allows PureHDF to use the C-Blosc2 compression algorithm.

```cs
using PureHDF.Filters;

H5Filter.Register(new Blosc2Filter());
```

--------------------------------

### Initialize New HDF5 File

Source: https://github.com/apollo3zehn/purehdf/blob/dev/README.md

Create a new H5File instance to begin constructing an HDF5 file. An H5File acts as the root group.

```csharp
var file = new H5File();
```

--------------------------------

### Open an HDF5 file for reading

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/index.md

Initializes a connection to an HDF5 file using the OpenRead method.

```cs
using PureHDF;

var file = H5File.OpenRead("path/to/file.h5");
```

--------------------------------

### Run .NET Benchmark with Profiler

Source: https://github.com/apollo3zehn/purehdf/blob/dev/benchmarks/PureHDF.Benchmarks/README.md

Execute a specific .NET benchmark using the `dotnet run` command. This command includes options for configuration, target framework, job selection, project path, filtering, and enabling the 'perf' profiler.

```bash
sudo dotnet run \
    -c Release \
    -f net8.0 \
    --job short \
    --project benchmarks/PureHDF.Benchmarks/PureHDF.Benchmarks.csproj \
    --filter '*chunked_no_filter*' \
    --profiler perf
```

--------------------------------

### Construct and Write HDF5 File

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/index.md

Define a complete file structure and persist it to disk.

```csharp
using PureHDF;

var file = new H5File()
{
    ["my-group"] = new H5Group()
    {
        ["numerical-dataset"] = new double[] { 2.0, 3.1, 4.2 },
        ["string-dataset"] = new string[] { "One", "Two", "Three" },
        Attributes = new()
        {
            ["numerical-attribute"] = new double[] { 2.0, 3.1, 4.2 },
            ["string-attribute"] = new string[] { "One", "Two", "Three" }
        }
    }
};
```

```csharp
file.Write("path/to/file.h5");
```

--------------------------------

### Accessing a Dataset with Intellisense

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/intellisense.md

Shows how to access a dataset using the generated bindings provided by PureHDF.SourceGenerator for improved IDE intellisense.

```cs
var dataset = bindings.group1.sub_dataset2;
```

--------------------------------

### Deferred Writing with H5File

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/index.md

Use BeginWrite to obtain a writer for incremental data writing.

```csharp
var data = Enumerable.Range(0, 100).ToArray();
var dataset = new H5Dataset<int[]>(fileDims: [(ulong)data.Length]);

var file = new H5File
{
    ["my-dataset"] = dataset
};

using var writer = file.BeginWrite("path/to/file.h5");
writer.Write(dataset, data);
```

--------------------------------

### Write Object References in HDF5

Source: https://github.com/apollo3zehn/purehdf/blob/dev/CHANGELOG.md

Demonstrates how to write object references to an HDF5 file, including datasets and groups. Ensure the HDF5 file is properly initialized before writing references.

```cs
var dataset = new H5Dataset(data: 1);
var group = new H5Group();

var file = new H5File
{
    ["data"] = dataset,
    ["group"] = group,
    ["references"] = new H5ObjectReference[] { dataset, group }
};
```

--------------------------------

### Accessing a Dataset with PureHDF

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/intellisense.md

Demonstrates the standard way to access a dataset within a group in an HDF5 file using PureHDF before source generators.

```cs
using var h5File = H5File.OpenRead(FILE_PATH);
    var dataset = h5File.Group("group1").Dataset("sub_dataset2");
```

--------------------------------

### Provide Custom Buffer for Dataset Reading

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/performance.md

Use .NET's MemoryPool to rent a buffer for reading dataset into memory, allowing for custom memory management.

```cs
var dataset = (NativeDataset)file.Dataset("/the/dataset");
var length = (int)dataset.Space.Dimensions[0] * sizeof(double);

using var memoryOwner = MemoryPool<byte>.Shared.Rent(minBufferSize: length);
var memory = memoryOwner.Memory.Slice(0, length);

dataset.Read(buffer: memory);

var doubleData = MemoryMarshal.Cast<byte, double>(memory.Span);
```

--------------------------------

### Create HDF5 Group with Datasets

Source: https://github.com/apollo3zehn/purehdf/blob/dev/README.md

Instantiate an H5Group and populate it with datasets using a dictionary collection initializer. Supports various data types.

```csharp
var group = new H5Group()
{
    ["numerical-dataset"] = new double[] { 2.0, 3.1, 4.2 },
    ["string-dataset"] = new string[] { "One", "Two", "Three" }
}
```

--------------------------------

### Create H5Group

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/index.md

Instantiate an empty H5Group or one populated with datasets using a collection initializer.

```csharp
var group = new H5Group();
```

```csharp
var group = new H5Group()
{
    ["numerical-dataset"] = new double[] { 2.0, 3.1, 4.2 },
    ["string-dataset"] = new string[] { "One", "Two", "Three" }
};
```

--------------------------------

### Configure Global Filters with H5WriteOptions

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/filters.md

Use H5WriteOptions to set filters for all datasets written to a file. Ensure PureHDF.Filters namespace is imported.

```cs
using PureHDF.Filters;

var options = new H5WriteOptions(
    Filters:
    [
        ShuffleFilter.Id,
        DeflateFilter.Id
    ]
);

file.Write("path/to/file.h5", options);
```

--------------------------------

### Initialize HsdsConnector in C#

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/hsds.md

Connects to an HSDS server and retrieves a group from a specified domain. Requires the hsds-api package.

```cs
var domainName = "/shared/tall.h5";
var client = new HsdsClient(new Uri("http://hsdshdflab.hdfgroup.org"));
var root = HsdsConnector.Create(domainName, client);
var group = root.Group("/my-group");

...
```

--------------------------------

### Configure Filter Parameters with H5Filter

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/filters.md

Configure specific filter parameters, such as compression level and algorithm for Blosc2, using a dictionary within the H5Filter constructor. The dictionary keys are constants defined in the respective filter classes.

```cs
var options = new H5WriteOptions(
    Filters:
    [
        new H5Filter(Id: ShuffleFilter.Id, Options: new() 
        {
            [Blosc2Filter.COMPRESSION_LEVEL] = 9,
            [Blosc2Filter.COMPRESSOR_CODE] = "blosclz"
        })
    ]
);

file.Write("path/to/file.h5", options);
```

--------------------------------

### Construct Full HDF5 File Structure

Source: https://github.com/apollo3zehn/purehdf/blob/dev/README.md

Build a complete HDF5 file structure including a root group, a subgroup, datasets, and attributes. This demonstrates nested HDF5 objects.

```csharp
var file = new H5File()
{
    ["my-group"] = new H5Group()
    {
        ["numerical-dataset"] = new double[] { 2.0, 3.1, 4.2 },
        ["string-dataset"] = new string[] { "One", "Two", "Three" },
        Attributes = new()
        {
            ["numerical-attribute"] = new double[] { 2.0, 3.1, 4.2 },
            ["string-attribute"] = new string[] { "One", "Two", "Three" }
        }
    }
};
```

--------------------------------

### Parallel Reading with Memory-Mapped File

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/concurrency.md

Demonstrates reading data in parallel using a MemoryMappedFile accessor. Requires the use of a unique cache per read operation.

```cs
using System.IO.MemoryMappedFiles;

const ulong TOTAL_ELEMENT_COUNT = xxx;
const ulong SEGMENT_COUNT = xxx;
const ulong SEGMENT_SIZE = TOTAL_ELEMENT_COUNT / SEGMENT_COUNT;

using var mmf = MemoryMappedFile.CreateFromFile(FILE_PATH);
using var accessor = mmf.CreateViewAccessor();
using var file = H5File.Open(accessor);

var dataset = file.Dataset("xxx");
var buffer = new float[TOTAL_ELEMENT_COUNT];

Parallel.For(0, SEGMENT_COUNT, i =>
{
    var start = i * SEGMENT_SIZE;
    var partialBuffer = buffer.Slice(start, length: SEGMENT_SIZE);
    var fileSelection = new HyperslabSelection(start, block: SEGMENT_SIZE)

    dataset.Read<float>(partialBuffer, fileSelection);
});
```

--------------------------------

### Create a PointSelection

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/slicing.md

Point selections require a 2D array where each row represents a coordinate point in the dataset's rank space.

```csharp
using PureHDF.Selections;

var selection = new PointSelection(new ulong[,] {
    { 00, 00, 00 },
    { 00, 05, 10 },
    { 12, 01, 10 },
    { 05, 07, 09 }
});
```

--------------------------------

### Open HDF5 File from Amazon S3

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/amazon-s3.md

Initialize an AmazonS3Client and AmazonS3Stream to open an HDF5 file. The stream uses 1 MB cache slots by default.

```csharp
using PureHDF.VFD.AmazonS3

// adapt to your needs
var credentials = new AnonymousAWSCredentials();
var region = RegionEndpoint.EUWest1;
var client = new AmazonS3Client(credentials, region);
var s3Stream = new AmazonS3Stream(client, bucketName: "xxx", key: "yyy");

using var file = H5File.Open(s3Stream);

...
```

--------------------------------

### Implement Custom IH5Filter

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/filters.md

Create a custom filter by deriving from the IH5Filter interface. Implement the FilterId, Name, Filter, and GetParameters methods. The GetParameters method is only required for compression.

```cs
public class MyFilter : IH5Filter
{
    public ushort FilterId => <your filter ID>;
    public string Name => "<your filter name>";

    public Memory<byte> Filter(FilterInfo info)
    {
        throw new NotImplementedException();
    }

    public uint[] GetParameters(uint[] chunkDimensions, uint typeSize, Dictionary<string, object>? options)
    {
        throw new NotImplementedException();
    }
}
```

--------------------------------

### Write HDF5 File to Disk

Source: https://github.com/apollo3zehn/purehdf/blob/dev/README.md

Save the constructed HDF5 file to a specified path on the file system. Ensure the path is valid and writable.

```csharp
file.Write("path/to/file.h5");
```

--------------------------------

### Read HDF5 File Components

Source: https://github.com/apollo3zehn/purehdf/blob/dev/README.md

Open an HDF5 file for reading and access its groups, attributes, and datasets. Ensure the file path is correct.

```csharp
// root group
var file = H5File.OpenRead("path/to/file.h5");

// sub group
var group = file.Group("path/to/group");

// attribute
var attribute = group.Attribute("my-attribute");
var attributeData = attribute.Read<int>();

// dataset
var dataset = group.Dataset("my-dataset");
var datasetData = dataset.Read<double>();
```

--------------------------------

### Configure Reading Chunk Cache

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/performance.md

Customize the reading chunk cache by specifying the number of chunk slots and the maximum total byte size for the cache.

```cs
var dataset = (NativeDataset)file.Dataset("/the/dataset");

var datasetAccess = new H5DatasetAccess(
    ChunkCache: new SimpleReadingChunkCache(
        chunkSlotCount: 521,
        byteCount: 1 * 1024 * 1024
    )
)

dataset.Read<T>(datasetAccess, ...);
```

--------------------------------

### Configure Virtual Dataset Prefix in C#

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/external-files.md

Set the VirtualPrefix within H5DatasetAccess when working with virtual datasets. This requires the PureHDF.VOL.Native namespace.

```cs
using PureHDF.VOL.Native;

var dataset = (NativeDataset)root.Dataset(...);

var datasetAccess = new H5DatasetAccess(
    VirtualPrefix: prefix 
);

var data = dataset.Read<float[]>(..., datasetAccess: datasetAccess);
```

--------------------------------

### Create Soft Links

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/index.md

Link to existing groups or datasets within the HDF5 file using H5SoftLink.

```csharp
var file = new H5File
{
    ["group_1"] = new H5Group
    {
        ["dataset"] = new int[] { 1, 2, 3 }
    },

    ["group_2"] = new H5Group
    {
        /* soft link to a group */
        ["soft_link_1"] = new H5SoftLink("/group_1"),

        /* soft link to a dataset */
        ["soft_link_2"] = new H5SoftLink("/group_1/dataset")
    }
};
```

--------------------------------

### Provide Custom Writing Chunk Cache

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/performance.md

Implement and provide a custom IWritingChunkCache to the H5Dataset constructor for advanced control over writing operations.

```cs
var datasetCreation = new H5DatasetCreation(
    ChunkCache: <your own chunk cache>
)

var dataset = new H5Dataset(..., datasetCreation: datasetCreation);
```

--------------------------------

### Create Object References in H5File

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/data-types.md

Use H5ObjectReference to create references to datasets. H5Dataset can be implicitly cast to H5ObjectReference.

```csharp
var dataset1 = new H5Dataset(data: 1);
var dataset2 = new H5Dataset(data: 2);

var file = new H5File
{
    ["data1"] = dataset1,
    ["data2"] = dataset2,
    ["reference"] = new H5ObjectReference[] { dataset1, dataset2 }
};
```

--------------------------------

### Register Deflate (SharpZipLib) Filter in PureHDF

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/filters.md

Register the Deflate filter based on SharpZipLib. Ensure the PureHDF.Filters.Deflate.SharpZipLib package is added.

```csharp
using PureHDF.Filters;

H5Filter.Register(new DeflateSharpZipLibFilter());
```

--------------------------------

### Write Basic Data to H5File

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/data-types.md

Add simple or complex data to an H5File or H5Group dictionary.

```csharp
var file = new H5File()
{
    ["my-dataset"] = data // data contains the simple or complex data you want to write
};
```

--------------------------------

### Create a DelegateSelection

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/slicing.md

Delegate selections use a custom walker function to yield data steps, requiring the total element count to be specified.

```csharp
static IEnumerable<Step> Walker(ulong[] datasetDimensions)
{
    yield return new Step(Coordinates: [00, 00, 00], ElementCount: 1);
    yield return new Step(Coordinates: [00, 05, 10], ElementCount: 5);
    yield return new Step(Coordinates: [12, 01, 10], ElementCount: 2);
    yield return new Step(Coordinates: [05, 07, 09], ElementCount: 3);
};

var selection = new DelegateSelection(totalElementCount: 11, Walker);
```

--------------------------------

### Configure External Link Prefix in C#

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/external-files.md

Use H5LinkAccess to specify the ExternalLinkPrefix when accessing external links. Ensure the PureHDF.VOL.Native namespace is imported.

```cs
using PureHDF.VOL.Native;

var group = (NativeGroup)root.Group(...);

var linkAccess = new H5LinkAccess(
    ExternalLinkPrefix: prefix 
);

var dataset = group.Dataset(path, linkAccess);
```

--------------------------------

### Write Opaque Data using H5OpaqueInfo

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/data-types.md

Treat byte arrays as opaque data by passing an H5OpaqueInfo instance to the H5Dataset constructor.

```csharp
var data = new byte[] { 0x01, 0x02, 0x03, 0x04 };

var opaqueInfo = new H5OpaqueInfo(
    TypeSize: (uint)data.Length,
    Tag: "My tag"
);

var file = new H5File
{
    ["opaque"] = new H5Dataset(data, opaqueInfo: opaqueInfo)
};

file.Write("path/to/file.h5");
```

--------------------------------

### Write Data in Chunks

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/index.md

Use selections to write specific slices of data to a dataset.

```csharp
using PureHDF.Selections;

var fileSelection = new HyperslabSelection(start: 2, block: 5);
writer.Write(dataset, data, fileSelection: fileSelection);
```

--------------------------------

### Configure Filters for a Single Dataset

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/filters.md

Set filters for an individual dataset during its creation using H5DatasetCreation. This allows for dataset-specific filter pipelines.

```cs
var datasetCreation = new H5DatasetCreation(
    Filters:
    [
        ShuffleFilter.Id,
        DeflateFilter.Id
    ]
)

var dataset = new H5Dataset(..., datasetCreation: datasetCreation);
```

--------------------------------

### Register LZF Filter in PureHDF

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/filters.md

Add the PureHDF.Filters.LZF package and use this code to register the LZF filter.

```csharp
using PureHDF.Filters;

H5Filter.Register(new LzfFilter());
```

--------------------------------

### Configure External File Prefix for Dataset in C#

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/external-files.md

Utilize H5DatasetAccess to set the ExternalFilePrefix for reading data from external files. The PureHDF.VOL.Native namespace is required.

```cs
using PureHDF.VOL.Native;

var dataset = (NativeDataset)root.Dataset(...);

var datasetAccess = new H5DatasetAccess(
    ExternalFilePrefix: prefix 
);

var data = dataset.Read<float[]>(..., datasetAccess: datasetAccess);
```

--------------------------------

### Read partial dataset using selections

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/slicing.md

Pass fileSelection or memorySelection to the Read method to restrict the data read from the file or mapped to the memory buffer.

```csharp
var fileSelection = ...;
var data = dataset.Read<int[]>(fileSelection: fileSelection);
```

```csharp
var memorySelection = ...;
var data = dataset.Read<int[]>(memorySelection: memorySelection);
```

--------------------------------

### Map .NET Property Names to HDF5 Compound Field Names

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/data-types.md

Use H5Name attribute and a PropertyNameMapper function to control compound field names in HDF5 files.

```csharp
class MyClass
{
    [property: H5Name("my-name")]
    public double Y { get; set; }
}

string? PropertyNameMapper(PropertyInfo propertyInfo)
{
    var attribute = propertyInfo.GetCustomAttribute<H5NameAttribute>();
    return attribute is not null ? attribute.Name : default;
}

var options = new H5WriteOptions(
    PropertyNameMapper: propertyNameMapper
);

file.Write(filePath, options);
```

--------------------------------

### Define Struct for Simple Compound Data

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/compound.md

Use StructLayout and FieldOffset attributes to map struct fields to HDF5 compound data offsets. Ensure field offsets match the HDF5 file definition.

```cs
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Explicit, Size = 5)]
struct SimpleStruct
{
    [FieldOffset(0)]
    public byte ByteValue;

    [FieldOffset(1)]
    public ushort UShortValue;

    [FieldOffset(3)]
    public TestEnum EnumValue;
}
```

--------------------------------

### Read Unknown Compound Data as Dictionary

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/compound.md

Use this method when the structure of the HDF5 compound is unknown or too large to define. The returned dictionary's values can be various .NET types, including nested dictionaries or arrays.

```csharp
dataset.Read<Dictionary<string, object>>()
```

--------------------------------

### Access objects within an HDF5 file

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/index.md

Retrieves specific groups, datasets, or generic objects from an open HDF5 file instance.

```cs
var group = file.Group("/path/to/my/group");
var dataset = file.Dataset("/path/to/my/dataset");
var commitedDataType = file.Group("/path/to/my/datatype");
var unknownObject = file.Get("/path/to/my/unknown/object");
```

--------------------------------

### Create Chunked HDF5 Dataset

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/chunks.md

Specify chunk dimensions when creating an H5Dataset to enable chunking. If no chunks or filters are specified, data is written as compact or contiguous datasets.

```cs
var dataset = new H5Dataset(
    data, 
    chunks: [10, 10]);
```

--------------------------------

### Configure H5ReadOptions with Custom Field Name Mapper

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/compound.md

Create a FieldNameMapper function to translate struct field information to HDF5 member names. This allows using custom field names in your struct.

```cs
// Create a name translator.
using System.Reflection;

Func<FieldInfo, string?> converter = fieldInfo =>
{
    var attribute = fieldInfo.GetCustomAttribute<H5NameAttribute>(true);
    return attribute is not null ? attribute.Name : null;
};

// Use that name translator.
var options = new H5ReadOptions() { FieldNameMapper = converter };
var h5file = H5File.OpenRead(..., options);
var dataset = h5file.Dataset(...);
var compoundData = dataset.Read<NullableStructWithCustomFieldName>();
```

--------------------------------

### Explicitly define dataset dimensions

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/dimensions.md

Use the fileDims parameter to manually specify the shape of the dataset when the input data structure does not match the desired HDF5 layout.

```cs
// Create a 100x100 dataset - the data itself must be an
// array-like type with a total of 100x100 = 10.000 elements. */
var dataset = new H5Dataset(data, fileDims: [100, 100]);
```

--------------------------------

### Register Bitshuffle Filter in PureHDF

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/filters.md

Register the Bitshuffle filter by adding the PureHDF.Filters.Bitshuffle package and using this code.

```csharp
using PureHDF.Filters;

H5Filter.Register(new BitshuffleFilter());
```

--------------------------------

### Read Compound Data with Reference Types

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/compound.md

Read compound data with reference types into a struct. This invokes a slower code path to decode variable-length data.

```cs
var compoundData = dataset.Read<NullableStruct>();
```

--------------------------------

### Define Struct for Compound Data with Reference Types

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/compound.md

Define a struct to read compound data containing reference types like strings and arrays. Field names must match HDF5 file members exactly.

```cs
struct NullableStruct
{
    public float FloatValue;
    public string StringValue1;
    public string StringValue2;
    public byte ByteValue;
    public short ShortValue;
    public float[] FloatArray;
}
```

--------------------------------

### Add Attributes to H5Group

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/index.md

Assign attributes to a group using the Attributes property.

```csharp
var group = new H5Group()
{
    Attributes = new()
    {
        ["numerical-attribute"] = new double[] { 2.0, 3.1, 4.2 },
        ["string-attribute"] = new string[] { "One", "Two", "Three" }
    }
};
```

--------------------------------

### Write Nullable Value Types using Generic H5Dataset

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/data-types.md

Use the generic H5Dataset<T> to write nullable value types, including null. This preserves type information lost with null.

```csharp
int? value = 1; // or null

var file = new H5File()
{
    ["my-dataset"] = new H5Dataset<int?>(value)
};
```

--------------------------------

### Read Simple Compound Data

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/compound.md

Read compound data into a predefined struct when it does not contain string-like or array-like members. This uses a high-performance copy operation.

```cs
var compoundData = dataset.Read<SimpleStruct>();
```

--------------------------------

### Add Attributes to HDF5 Group

Source: https://github.com/apollo3zehn/purehdf/blob/dev/README.md

Add attributes to an H5Group using the 'Attributes' property and a dictionary initializer. Attributes can store various data types.

```csharp
var group = new H5Group()
{
    Attributes = new()
    {
        ["numerical-attribute"] = new double[] { 2.0, 3.1, 4.2 },
        ["string-attribute"] = new string[] { "One", "Two", "Three" }
    }
}
```

--------------------------------

### Iterate over group children

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/index.md

Enumerates objects within a group and identifies their type using pattern matching.

```cs
foreach (var link in group.Children())
{
    var message = link switch
    {
        IH5Group childGroup                 => $"I am a group and my name is '{childGroup.Name}'.",
        IH5Dataset childDataset             => $"I am a dataset, call me '{childDataset.Name}'.",
        IH5CommitedDatatype childDatatype   => $"I am the data type '{childDatatype.Name}'.",
        IH5UnresolvedLink lostLink          => $"I cannot find my link target =( shame on '{lostLink.Name}'.",
        _                                   => throw new Exception("Unknown link type")
    };

    Console.WriteLine(message);
}
```

--------------------------------

### Determine dataset shape from multidimensional arrays

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/writing/dimensions.md

The library automatically infers the dataset dimensions from the structure of the provided multidimensional array.

```cs
// Create a 3x3 dataset - no `fileDims` parameter required
var data = new int[,] 
{
    { 0, 1, 2 },
    { 3, 4, 5 },
    { 6, 7, 8 }
};

var dataset = new H5Dataset(data);
```

--------------------------------

### Define Struct with Custom Field Names using H5NameAttribute

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/compound.md

Use the H5NameAttribute to map struct fields to HDF5 members with different names. This is useful when struct field names do not match HDF5 member names.

```cs
// Apply the H5NameAttribute to the field with custom name.
struct NullableStructWithCustomFieldName
{
    [H5Name("FloatValue")]
    public float FloatValueWithCustomName;

    // ... more fields
}
```

--------------------------------

### Read dataset data

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/index.md

Reads data from a dataset or attribute into a specified generic type, including support for multi-dimensional and jagged arrays.

```cs
var intScalar = dataset.Read<int>();
var doubleArray = dataset.Read<double[]>();
var double2DArray = dataset.Read<double[,]>();
var double3DArray = dataset.Read<double[,,]>();
var floatJaggedArray = dataset.Read<float[][]>(); /* This works only for variable length sequences */
```

--------------------------------

### Define Struct for Compound Data with Fixed-Size Array

Source: https://github.com/apollo3zehn/purehdf/blob/dev/doc/reading/compound.md

For compound data containing fixed-size arrays, add the 'unsafe' modifier to the struct and define the array field using 'fixed'.

```cs
[StructLayout(LayoutKind.Explicit, Size = 8)]
unsafe struct SimpleStructWithArray
{
    // ... all the fields from the struct above, plus:

    [FieldOffset(5)]
    public fixed float FloatArray[3];
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.