Implement basic functionality.

This commit implements basic functionality.
- Supported codecs include Sharding Indexed, Gzip, Crc32c, Transpose and
  Bytes.
- Supported stores include MemoryStore and FilesystemStore.
- Supported data types include Float32, Float64, Complex32 and
  Complex64. This limitation is simply a result of Owl limited
  array write functionality as reported here: owlbarn/owl#671
- All the core Zarr V3 specification details have been implemented.

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2024, zoj613
+Copyright (c) 2024, Zolisa Bleki
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

README.md

@@ -1,2 +1,112 @@
 # zarr-ml
-An Ocaml implementation of the Zarr version 3 specification.
+An implementation of the Zarr version 3 specification.
+
+
+## Example
+```ocaml
+open Zarr
+open Zarr.Codecs
+open Zarr.Storage
+open Zarr.Metadata
+open Zarr.Extensions
+module Ndarray = Owl.Dense.Ndarray.Generic
+
+let store =
+ Result.get_ok @@
+ FilesystemStore.open_or_create ~file_perm:0o777 "testdata.zarr";;
+
+let group_node =
+ Result.get_ok @@ Node.of_path "/some/group";;
+
+FilesystemStore.create_group store group_node;;
+
+let array_node =
+ Result.get_ok @@ Node.(group_node / "name");;
+
+let shard_config = {
+ chunk_shape = [|5; 5; 10|];
+ codecs = Chain.create [] (Bytes Little) [Gzip L5];
+ index_codecs = Chain.create [] (Bytes Big) [Crc32c];
+ index_location = Start
+};;
+let codec_chain =
+ Chain.create [Transpose [|0; 1; 2|]] (ShardingIndexed shard_config) [];;
+
+FilesystemStore.create_array
+ ~codecs:codec_chain
+ ~shape:[|100; 100; 50|]
+ ~chunks:[|15; 15; 20|]
+ (FillValue.Float Float.neg_infinity)
+ Datatype.Float32
+ array_node
+ store;;
+
+FilesystemStore.find_all_nodes store |> List.map Node.to_path;;
+(* - : string list = ["/"; "/some"; "/some/group/name"; "/some/group"] *)
+
+let slice = Owl_types.[|R [0; 20]; I 10; R []|];;
+let x =
+ Result.get_ok @@
+ FilesystemStore.get_array array_node slice Bigarray.Float32 store;;
+(*
+ C0 C1 C2 C3 C4 C45 C46 C47 C48 C49 
+ R[0,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+ R[1,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+ R[2,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+ R[3,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+ R[4,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+ ... ... ... ... ... ... ... ... ... ... ... 
+R[16,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+R[17,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+R[18,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+R[19,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF 
+R[20,0] -INF -INF -INF -INF -INF ... -INF -INF -INF -INF -INF *)
+
+(* Do some computation on the array slice *)
+let x' = Ndarray.map (fun _ -> Owl_stats_dist.uniform_rvs 0. 100.) x;;
+FilesystemStore.set_array array_node slice x' store;;
+
+FilesystemStore.get_array
+ array_node
+ Owl_types.[|R [0; 73]; L [10; 16]; R[0; 5]|]
+ Bigarray.Float32
+ store;;
+(*
+ C0 C1 C2 C3 C4 C5 
+ R[0,0] 68.0272 44.914 85.2431 39.0772 26.582 16.577 
+ R[0,1] -INF -INF -INF -INF -INF -INF 
+ R[1,0] 88.418 77.0368 43.4968 45.1263 8.95641 76.9155 
+ R[1,1] -INF -INF -INF -INF -INF -INF 
+ R[2,0] 98.4036 77.8744 67.6689 56.8803 37.0718 97.042 
+ ... ... ... ... ... ... 
+R[71,1] -INF -INF -INF -INF -INF -INF 
+R[72,0] -INF -INF -INF -INF -INF -INF 
+R[72,1] -INF -INF -INF -INF -INF -INF 
+R[73,0] -INF -INF -INF -INF -INF -INF 
+R[73,1] -INF -INF -INF -INF -INF -INF *)
+
+FilesystemStore.reshape store array_node [|25; 32; 10|];;
+FilesystemStore.get_array
+ array_node
+ Owl_types.[|R []; I 10; R[0; 5]|]
+ Bigarray.Float32
+ store;;
+(*
+ C0 C1 C2 C3 C4 C5 
+ R[0,0] 68.0272 44.914 85.2431 39.0772 26.582 16.577 
+ R[1,0] 88.418 77.0368 43.4968 45.1263 8.95641 76.9155 
+ R[2,0] 98.4036 77.8744 67.6689 56.8803 37.0718 97.042 
+ R[3,0] 22.8653 20.1767 88.9549 22.1052 9.86822 10.8826 
+ R[4,0] 55.6043 93.8599 60.3723 40.543 46.8199 97.282 
+ ... ... ... ... ... ... 
+R[20,0] 61.2473 78.8035 52.3056 59.5631 78.2462 52.4205 
+R[21,0] -INF -INF -INF -INF -INF -INF 
+R[22,0] -INF -INF -INF -INF -INF -INF 
+R[23,0] -INF -INF -INF -INF -INF -INF 
+R[24,0] -INF -INF -INF -INF -INF -INF *)
+
+FilesystemStore.array_metadata array_node store
+|> Result.get_ok
+|> ArrayMetadata.shape;;
+(* - : int array = [|25; 32; 10|] *)
+```

dune-project

@@ -0,0 +1,34 @@
+(lang dune 3.15)
+
+(name zarr)
+
+(generate_opam_files true)
+
+(source
+ (github zoj613/zarr-ml))
+
+(authors "Author Name")
+
+(maintainers "Maintainer Name")
+
+(license BSD-3-Clause)
+
+(documentation https://url/to/documentation)
+
+(package
+ (name zarr)
+ (synopsis "A short synopsis")
+ (description "A longer description")
+ (depends
+ dune
+ (ocaml (>= 4.14.2))
+ yojson
+ ppx_derviving_yojson
+ ezgzip
+ checkseum
+ stdint
+ owl)
+ (tags
+ (topics "to describe" your project)))
+
+; See the complete stanza docs at https://dune.readthedocs.io/en/stable/dune-files.html#dune-project

lib/codecs/array_to_array.ml

@@ -0,0 +1,66 @@
+module Ndarray = Owl.Dense.Ndarray.Generic
+
+type dimension_order = int array
+
+type array_to_array =
+ | Transpose of dimension_order
+
+type error =
+ [ `Invalid_transpose_order of dimension_order * string ]
+
+(* https://zarr-specs.readthedocs.io/en/latest/v3/codecs/transpose/v1.0.html *)
+module TransposeCodec = struct
+ type config = {order : int array} [@@deriving yojson]
+ type transpose = config Util.ext_point [@@deriving yojson]
+
+ let compute_encoded_size input_size = input_size
+
+ let encode o x =
+ try Ok (Ndarray.transpose ~axis:o x) with
+ | Failure s -> Error (`Invalid_transpose_order (o, s))
+
+ let decode o x =
+ let inv_order = Array.(make (length o) 0) in
+ Array.iteri (fun i x -> inv_order.(x) <- i) o;
+ try Ok (Ndarray.transpose ~axis:inv_order x) with
+ | Failure s -> Error (`Invalid_transpose_order (o, s))
+
+ let to_yojson order =
+ transpose_to_yojson
+ {name = "transpose"; configuration = {order}}
+
+ let parse_order o =
+ let o' = Array.copy o in
+ Array.fast_sort Int.compare o';
+ if o' <> Array.init (Array.length o') Fun.id then
+ Error (`Invalid_transpose_order (o, ""))
+ else
+ Result.ok @@ Transpose o
+
+ let of_yojson x =
+ let open Util.Result_syntax in
+ transpose_of_yojson x >>= fun trans ->
+ parse_order trans.configuration.order
+ >>? fun (`Invalid_transpose_order _) -> "Invalid transpose order"
+end
+
+module ArrayToArray = struct
+ let compute_encoded_size input_size = function
+ | Transpose _ -> TransposeCodec.compute_encoded_size input_size
+
+ let encode t x =
+ match t with
+ | Transpose order -> TransposeCodec.encode order x
+
+ let decode t x =
+ match t with
+ | Transpose order -> TransposeCodec.decode order x
+
+ let to_yojson = function
+ | Transpose order -> TransposeCodec.to_yojson order
+
+ let of_yojson x =
+ match Util.get_name x with
+ | "transpose" -> TransposeCodec.of_yojson x
+ | s -> Error ("array->array codec not supported: " ^ s)
+end

lib/codecs/array_to_array.mli

@@ -0,0 +1,23 @@
+module Ndarray = Owl.Dense.Ndarray.Generic
+
+type dimension_order = int array
+
+type array_to_array =
+ | Transpose of dimension_order
+
+type error =
+ [ `Invalid_transpose_order of dimension_order * string ]
+
+module ArrayToArray : sig 
+ val compute_encoded_size : int -> array_to_array -> int
+ val encode
+ : array_to_array ->
+ ('a, 'b) Ndarray.t ->
+ (('a, 'b) Ndarray.t, [> error]) result
+ val decode
+ : array_to_array ->
+ ('a, 'b) Ndarray.t ->
+ (('a, 'b) Ndarray.t, [> error]) result
+ val of_yojson : Yojson.Safe.t -> (array_to_array, string) result
+ val to_yojson : array_to_array -> Yojson.Safe.t
+end