Repository navigation
Releases
v0.28.11 Backends 🏃♀️ and Dynamic Shapes 🤸
- New
onnxbackend, based on ONNX Runtime. Use-tags=onnxto include it in thebackends/defaultpackage. It has support for "onnx:cpu", "onnx:cuda" (CUDA) and "onnx:rocm" versions support. For WebAssembly (WASM) it supports "onnx:wasm" (CPU), "webgpu" (GPU) and "webnn" (experimental).- Includes saving a model to a
.onnxfile, that can be served with other inference systems that support ONNX (e.g. KnightAnalytics Hugot).
- Includes saving a model to a
- The "go" backend has been greatly optimized, closely matching "xla:cpu" speeds for FNN models (try out the UCI-Adult/Census model).
- The main execution engine has been updated to minimize synchronization costs;
- Improved buffer management;
- Updated and greatly broadened SIMD suport -- where possible using go1.27 portable
simd(so should work for any platforms). - Matrix multiplications are still very architecture dependent, hence only AVX2 and AVX512 were optimized so far. the microkernel was written in assembly due to some pending go
simdissues (#80829 and #78753). Consider donating for Apple hardware, I'd love to add support for Neon SIMD/assembly optimized kernels!
- Greatly improved DynamicShape support, with new ops to support it. This enabled creating ONNX models
with variable-sized inputs, from GoMLX trained (or fine-tuned) models.
v0.28.0 - 🎆 Large API update; Lots of new features
To faciliate conversion to this updated API, we added the CLI tool cmd/convert_v0.28.
It won't fully fix the code (mostly because of the context.Context to model.Store/model.Scope redesign),
but it will change the import package paths and names.
Remember to save your code before running the conversion -- allow yourself to revert to files where the fix
make things worse.
go run <path_to_gomlx>/cmd/convert_v0.28/main.go [-dir <directory>]
API Changes: backends and related packages moved to github.com/gomlx/compute
Highlights:
- Experimental SIMD support for amd64 for the Go backend.
- Gradiend Checkpointing: needed when training large models, to trade-off memory usage for recomputation.
- Transformers library that support many more classes of LLMs.
- LLM generator (that works this time), with KVCache support.
- The "xla" backend now supports many more options, including
preallocate=falseto prevent preallocating 75% of the
GPU memory (forxla:cuda) upfront. UseGOMLX_BACKEND=xla:helpand it will printout help on all options. - Added FlashAttention for
xla:cudabackends -- mimicking what Jax does, usingcuDNNimplementation.
Including backward propagation version, for faster training.
API Changes:
- Packages
backends,dtypes,shapesanddistributedmoved togithub.com/gomlx/compute - New
github.com/gomlx/computerepo will host what was in packagebackends.backends/simplegobackend now moved togithub.com/gomlx/compute/gobackend(no longer "simple").backends/xlabackend now moved togithub.com/gomlx/go-xla/compute/xla.backends/defaultstill imports both by default the "go" and the "xla" backends.
- XLA backends used for test in
support/testutilonly where the platform is supported (and if the tagnoxlais NOT selected). - New
tensors/dtensorto hold distributed tensors (previously inpkg/core/distributed). - Packages in
pkg/supportmoved togithub.com/gomlx/compute/support:- The following packages were moved:
xslices,xsync,setsandhumanize.
- The following packages were moved:
Reoganization of packages -- removed the pkg top-level directory
In Go making the exported packages under pkg was a reasonable convention before
the special meaning internal came about, but it stayed in use (and was adopted by
GoMLX even thought it was no longer needed).
We are taking the opportunity of the large API upgrade to remove the pkg top-level
directory, and move the packages to the root:
github.com/gomlx/gomlx/core/...-> `github.com/gomlx/gomlx/core/...github.com/gomlx/gomlx/ml/...-> `github.com/gomlx/gomlx/ml/...github.com/gomlx/gomlx/support/...-> `github.com/gomlx/gomlx/support/...
And a few small renaming:
ml/datasets->ml/datasetml/layers/regularizers->ml/layers/regularizerml/model/initializers->ml/model/initializerml/model/checkpoints->ml/model/checkpointml/train/optimizers->ml/train/optimizerml/train/losses->ml/train/loss
Scope Redesign
- Package
context->model Scope->StoreandScopeNewScope->NewStore(the only "global" one)Exec.*Exec*->Exec.*Call*; the methods with*Exec*still exist but are deprecated.- New
Execwrappers for fixed number of outputs:NewExec1(),NewExec2()andNewExec3()for graphs with one,
two or three outputs.
- New
- Using mostly
fullPathinstead of the split scope/key pairs. - Variables:
Scope.VariableWithValueGraph->Scope.VariableWithNodeValueInspectVariable->Store.GetVariableInspectVariableInScope->Scope.GetVariableSetValueGraph->SetNodeValue;ValueGraph->NodeValueVariable.ParameterNamebecause a private function incheckpointpackage.
- Added
model.GetStore(): it returns themodel.Storeattached to the current graph (it accepts a node also),
so many functions intrainand other packages can drop thes *model.Scope(ors *model.Store) parameter. - (internal) Graph parameters as well as variable nodes associated to a graph are now stored in the
graphStore,
which is attached to the Graph. This makes the separation cleaner, and they all get automatically GC'ed if
the Graph is destroyed (preventing some leaks).
Package ml/train:
NewTrainernow accepts generic functions matching theModelFnCompatibleconstraint. This allowsmodelFn
signatures to omit thespecparameter if not used, use named*graph.Nodeinput parameters, and return a single
*graph.Node(or up to 3 nodes) directly instead of a slice. The passed functions are automatically converted to the
canonical signature.- All standard examples (
adult,cifar,mnist,dogsvscats) and their corresponding Jupyter Notebooks have been
updated to use these simplified/cleaner signatures.
- All standard examples (
DatasetAPI change: updated to use iterators, and now yields aBatchstruct -- more convenient if we need
future extensions, and easier to ignore non-used fields (likeSpec).- Clarification of main loss vs regularization loss in
ml/train, added:AddMainLoss/GetMainLossto accumulate the main model losses;AddRegularizationLoss/GetRegularizationLossto accumulate regularization losses;TotalLossto return their sum.- Older API marked as deprecated.
- Changed default loss metrics behavior to only return the total loss by default (named "Loss" / "~loss"). Added
WithMainLossMetric()method to include the "no-reg" metrics when requested.
Package ml/dataset:
- Updated
DatasetandBatchtypes, and adjusted various datasets implementations accordingly. - Added
dataset.Buffered, that pre-calculates the dataset. - Added
dataset.Map,dataset.ParallelMap,dataset.MapOnHostanddataset.ParallelMapOnHostto transform datasets.
Graph (github.com/gomlx/gomlx/core/graph):
Exec.*Exec*->Exec.*Call*; the methods with*Exec*still exist but are deprecated.- New
Execwrappers for fixed number of outputs:NewExec1,NewExec2andNewExec3for graphs with one, two or
three outputs.
- New
- New ops:
SchedulingBarrierandOptimizationBarrier: they are implemented in the Go and XLA backends.
- Gradient Checkpointing: Added
Node.Checkpoint()andNode.StopCheckpoint(). - Updates to
FusedScaledDotProductAttention, including adding support to the corresponding VJP: enabling the flash attention in XLA+CUDA.
Tensors (github.com/gomlx/gomlx/core/tensors):
- Renamed
FromAnyValuetoMustFromAnyValueand addedFromAnyValuereturning(tensor, error).
Other improvements
- Redesigned KVCache implementation (previous was broken) in
ml/layers/attention/kvcache: it is used by packagesattention,transformeranddecode. - Many improvements to
ml/zoo/transformer: it nows support Gemma4 class of transformer models. - Added
nn.SoftCapand in theml/layers/attentionadded support for attention scores soft-cap (used by Gemma models). - Added
activation.SwiGLUfor Swish Gated Linear activation, and updated corresponding support in thefnnpackage. - Added Dynamic Tanh (DyT) "pseudo" normalizer (https://arxiv.org/abs/2503.10622).
v0.27.3: Improves sub-byte support, optimized raw-byte data transfers, FNN ensembles, and major transformer updates including BERT and Gemma models.
v0.27.3: Improves sub-byte support, optimized raw-byte data transfers, FNN ensembles, and major transformer updates including BERT and Gemma models.
Core:
- Package
tensors- Improving support for sub-byte data types (
Int4,Int2,Uint4,Uint2) - Added
FromShapeForBackend()to create new tensors with shared memory
if possible. - Added
ToDevice()and improved performance of MaterializeOnDevice when copying to shared buffers. - Improved
MutableBytes(), should improve the performance in some cases. - Added
FromRaw()to upload a tensor to a backend with the given raw data -- this is the most performant
way to upload raw data to the backend accelerator.
- Improving support for sub-byte data types (
- Package
dtypes- Added several slice creation/copying/casting functions for dtypes, using switch on types as opposed to
the slowerreflectpackage. Incorporated that into thetensorsimplementations, as well as exposed
it publicly (go-huggingfaceproject uses it). - Deprecated
dtypes.Memory().
- Added several slice creation/copying/casting functions for dtypes, using switch on types as opposed to
- Package
shapes- Added
ByteSize()method, with proper support for packed dtypes. - Deprecated
shapes.Memory().
- Added
- Package
graph- Added
CrossCosineSimilarity()operation. Graph.Compile()now returns an error instead of panicking -- API change: it's not a common way to compile
graphs (in GoMLX it's only used in tests), but it requires change for anyone using it directly.
- Added
Packages in pkg/ml
- Package
activations- Added
HardSigmoidactivation. - Modified the parametrized activations to be suffixed with
With:LeakyReluWith,HardSigmoidWith,HardSwishWith.
- Added
- Package
attention:- API clean up.
- Added
WithMask, a simplified mask input for when only using padding. - Dropout now takes a
*Nodeinstead of a float64, allowing dynamic dropout control. - Fixed mask and causal mask handling.
- Package
attention/pos:- Split
EncoderAPI intoQKEncoderandPreEncoder, to support different types of positional encoders. - Added
WithSlidingWindowto support "sliding attention" (the slow way).
- Split
- Package
layers/fnn:- Added
WithEnsembleSizeandWithEnsembleAxismethods for configuring parallel independent executions via ensembles.
- Added
- Package
transfromers:- Updates and fixes to the API; Added methods to build partial models:
AllLayers,ForwardLayer,LogitsFromEmbeddings,EmbedTokesn, etc. - Updated positional-encoder support.
- Added options
WithFinalNormalization,WithScalingOfTokenEmbeddings,WithArchitecture,WithSlidingWindow
andWithLayerTypes,WithEmbedNormalization,WithTokenTypeEmbedding. - Added BERT and Gemma types of models.
- Updates and fixes to the API; Added methods to build partial models:
Packages in pkg/support
- Added
humanizepackage:- It includes
Bytes(),Count(),Speed(),Underscores()andDuration(). - Replaces
fsutil.BytesETCanddustin/go-humanize.
- It includes
Backends:
- Package
xla:BufferToFlatDataandBufferFromFlatDatanow transfer using raw-bytes, for a slight gain in performance.
DotGeneral with AccumulatorDType; Transformer architecture parameter;
Core:
-
Package
graph:DotGeneralpassingAccumulatorDTypeandOutputDTypeto the backend (instead of assuming it doesn't implement and
converting it). Also, by default, half-precision floats use float32 as accumulator.- For the
xlabackend: added an "hacky" dependency from the variable (weights) to the lhs operand of theDotGeneral
operation: because XLA CPU creates a temporary re-layout of the weights, this dependency ensures that only one temporary
buffer is allocated at a time, along the layers of a model (in a 22Gb model with 48 layers, it saved 48Gb! in temporary memory)
- For the
-
Package
ml/model/transformer:- Added architecture parameter ("standard" or "gemma" values).
- Activation passed an
activations.Typevalues (instead of string) -- but conversion from string as a context hyperparameters still works. - Added
WithTransposedWeights()andWithCausalMask()options. - Simplified code.
-
Package
ml/layers- Added constants to normalization types.
Backends:
-
Backend
xla:- Updated dependency to
github.com/gomlx/go-xlato v0.2.2: with a fix to NVIDIA CUDA drivers path. - DotGeneral with unsupported accumulation dtypes (only float32 is supported): it automatically converts the
input dtype to the accumulation dtype first. - Added executable memory consumption logging if passing
-vmodule=executable=1. - Added
OptimizationBarrieroperation. Not exposed ingraphthough. - Added "hack" dependency on the weights of a DotGeneral operation to the lhs operand of the DotGeneral operation,
to hugely decrease temporary memory usage. See issue in openxla/stablehlo#2923
- Updated dependency to
-
Backend
simplego("go"):- DotGeneral with accumulation dtypes: it automatically converts the input dtype to the accumulation dtype first.
(With the exception of half-precision types, which use float32 as accumulator by default).
- DotGeneral with accumulation dtypes: it automatically converts the input dtype to the accumulation dtype first.
v0.27.1 Minor fixes and updates; ONNX-GoMLX examples now use v0.4.1.
-
Package
examples/...:- Updated
gemma3,mxbai-rerankandbert-base-nerto use the newonnx-gomlxv0.4.1 API, bumped dependency.
- Updated
-
Package
graph:FloorandCeiloperations now are identity for integer dtypes.
-
Package
simplego:- Removed panics during execution: return errors instead.
- Fixed missing annotation/stacktrace on not-implemented errors.
- Implemented
Pad()operation (and add some more tests ingraph.TestPad).
-
Package
xla:- Changed
TF_CPP_MIN_LOG_LEVELto default to 3. See openxla/xla#26466
- Changed
v0.27.0: Graph functions; Improved Go backend (fusion ops); Quantization dtypes; more ML layers & fixes
v0.27.0: Graph functions; Improved Go backend (fusion ops); Quantization dtypes; more ML layers & fixes
- Package
backends: major refactoring to add support for functions/closures.- Added
backends.Function, which now holds all the "ops" methods. - Added
NewFunction,ClosureandCall. - Renamed
backends.Op->backends.Value. - Added
FusedOps, allowing backends to expose fused (more efficient) operations -- with proper/automatic
fallback to decomposed operations when not supported or for gradients. - Added
ErrNotImplementederror andIsNotImplemented(err)function. - Added
Quantizationstruct,QuantizationScheme(Linear, NF4), andNF4LookupTable. - Removed
Dot()operation (redundant withDotGeneral). DotGeneral()now takes aDotGeneralConfigstruct, with options for setting the accumulator and output dtypes.
- Added
- Package
simplego:- Added
Float16support (thx @timkaye11) - Added dedup of computation nodes (aka. "common subexpression elimination" CSE) (thx @timkaye11, @janpfeifer)
- ~6% speedup for CSI-Adult demo training.
- DotGeneral: Pre-blocking of the blocked path, which may lead to deduplication of blocking nodes (@timekaye11).
- DotGeneral: Added smallMatMul execution path, optimized for small matrix multiplications (thx @timkaye11)
- Experimental
packgemmsupport leveraging simd operations (@ajroetker, @janpfeifer) - Funtions/closures support (thx @ajroetker)
- Added
Reverseoperation. - Added fused operations:
FusedGelu,FusedDense,FusedSoftmax,FusedLayerNorm,
FusedScaledDotProductAttention,FusedAttentionQKVProjection. - Added
FusedQuantizedDense: fused dequantization + matmul + bias + activation for Int4/Int8 weights
with Linear and NF4 quantization schemes, block-wise scales, and optional zero points. FusedScaledDotProductAttention: addedScaledDotProductAttentionConfigoptions struct with
QuantizedMatmulsflag for optional uint8 quantized Q@K/attn@V matmuls (awaiting go-highway
release for actual acceleration).Bitcastrefactored to pure bit reinterpretation; sub-byte unpacking moved toConvertDType.
- Added
- New package
bucketing:- Tools to manage bucketing of tensors (or anything else) -- thx @ajroetker
- Package
dtypes:- Added 'Uint2', 'Uint4', 'Int2', 'Int4'.
- Package
graph:- Added
Functionconcept (and support for closures) and theFunction.Calloperation. - Control Flow: Added
WhileandIfoperations. - Order operations: Added
Sort,SortFunc,TopK,BottomK. - Fixed
Bitcastfor packed sub-byte types: 8000Int4,Int2,Uint4andUint2, so they can be "bitcast"
back and forth from/touint8(bytes), to ease quantization. - Added
Atan2function. - Added test helper functions to test various backends at once.
- Fixed
Gathervalidation ofindexVectorAxisto check againststartIndicesrank instead ofoperandrank. Execgraph compilation is now concurrent, avoiding redundant compilations for the same graph shape.
- Added
- Package
ml/layers/attention: ImprovedMultiHeadAttention; AddedKVCachesupport.- Added Grouped Query Attention (GQA) support.
- Added
UseQKVProjection()option for fused Q/K/V Dense projection. FusedScaledDotProductAttentionnow supports boolean masks.
- Package
ml/layers/attention/pos: AddedPositionalEncoderinterface, and "RoPE" (Rotary Positional Encoding) implementation. - Package
ml/models/transformers:- Added a
Transformer"model": a collection of transformer layers are setup based on given configuration.
- Added a
- Package
ml/decode:
Added aDecoderobject to generate text given a sequential model. - Package
ml/decode/sample:- Added implementation of various sampling strategies (greedy, temperature, beam-search, top-k, top-p, etc.), used by the
decodepackage.
- Added implementation of various sampling strategies (greedy, temperature, beam-search, top-k, top-p, etc.), used by the
- Package
ml/layers/activations:- Added
HardSwish.
- Added
- Package
examples:- Separated in its own sub-module, to separate its dependencies.
- Added
gpt2: A simple GPT-2 implementation using the new transformers and decode packages. It downloads the model from HuggingFace. - Added
textgen: a minimal transformer text generation model that can be trained. - Added
gemma3: A simple Gemma 3 implementation using theonnx-gomlxpackage to convert the model, andgo-huggingfaceto download the model and run the tokenizer. - Added
mxbai-rerank: A cross-encoder reranking example using the MixedBread Reranker v1. It uses theonnx-gomlxpackage to convert the model, andgo-huggingfaceto download the model and run the tokenizer. - Added
BERT-base-NER: A BERT-base model fine-tuned for Named Entity Recognition.
- Bumped github actions versions to the new "Node24" ones.
v0.26.0: XLA by new github.com/gomlx/go-xla library. Added linux/arm64 and windows/amd64 support for XLA CPU.
API Change: dtypes package moved from github.com/gomlx/gopjrt/dtypes to github.com/gomlx/gomlx/pkg/core/dtypes.
It should be a simple change in import.
XLA:
- go-xla (replacing the now deprecated stablehlo and gopjrt libraries)
- Added auto-installation of standard (CPU and GPU/TPU when available) plugins.
(Can be disabled by setting the environment variableGOMLX_NO_AUTO_INSTALLto anything) - Fixed some memory leaks on plugin destruction;
- Improved performance in some low-latency scenarios (using GenPool as opposed to sync.Pool):
- Added auto-installation of standard (CPU and GPU/TPU when available) plugins.
- Removed old
gomlx/backends/xla(the one that used the retiredxlabuilderAPI for XLA). - Renamed
gomlx/backends/stablehlo-->gomlx/backends/xla, using the newgo-xlalibrary. - Added
xla.EnableAutoInstall(enabled bool)to enable/disable auto-installation of standard plugins.
And addedxla.AutoInstall()to immediately auto-install standard plugins. - Conversion from/to new
gomlx/gomlx/pkg/core/dtypes(andbfloat16) to/fromgomlx/gomlx/pkg/core/dtypes(and correspondingbfloat16) - Added linux/arm64 and windows/amd64 support for XLA CPU.
Other updates:
- Package
tensors:- Added
CopyFlatData()that returns an error (it was previously renamed toMustCopyFlatData)
- Added
- Package
graph:- Added 'RNGStateFromSeedForGraph' function to create a RNG state from a seed for a graph.
- Package
pkg/core/dtypes- New, copied from now deprecated Gopjrt.
- Package
simplego:- Registration of executors with priority.
v0.25.0 🎄🎅🤶 -> 🎁 Distributed execution 🎁; API cleanups (and changes)
This (early) end-of-year big release comes with a big 🎁: distributed execution. For anyone needing to scale the training (or inference), this is a must. As it goes with these new things, it should be considered experimental. I'll be actually using it, and hopefully any missing issues (including adding a distributed tutorial -- there is a demo already) will be solved by the end of the year, or early next year. 🦌
There is also some API clean ups -- mostly returning error in places that were panicking otherwise. So ... a bit of a "Grinch" gift, is the need for some updates, if you update to this version. All very trivial (added an error to the return list of some functions and methods).
We also had some external collaborations 🎉 Looking forward to more of those, there is so much interesting stuff to be done! (Quantization, using SIMD operations in the "Simple Go" backend, etc).
Hightlights:
-
Distributed (cross-devices) execution: with AutoSharding and SPMD strategies;
Also added support for "portable device" execution. -
API changes: (will require simple fixes)
- Most not graph building APIs now return errors (as opposed to panicking). Graph building functions
still use panic to return error -- otherwise it's too painful to express math. - All "Rng" renamed to "RNG" -- acronyms in Go are usually capitalized.
- Most not graph building APIs now return errors (as opposed to panicking). Graph building functions
Distributed computation improvements and refactorings:
- Package
graph:- Fixed/improved documentation.
- Added
IsNegative,IsPositive,IsNonNegative,IsNonPositive. - Added
SubScalarand tests for the '*Scalar' functions. - Added
Graph.WithDistributedStrategy,Graph.WithDeviceMesh.Graph.DeviceMeshandGraph.NumDevices - Added
Graph.Distributed()with "collective" (across devices) operations (likeAllReduce). - Renamed: s/
Exec.InDevice/Exec.WithDevice; s/Exec.SetName/Exec.WithName - Added
RunOnDevice. - Added
Exec.AutoShardingandExec.SPMD.
- Package
context:- Added
context.MustGetParam[T](ctx, key)andcontext.MustGetGraphParam[T](ctx, graph, key). - Added
Exec.AutoShardingandExec.SPMD. - Added
Variable.DistributedValueandVariable.SetDistributedValue.
- Added
- Package
train:- Added
train.DistributedDatasetandtrain.BaseDataset. Dataset.Resetnow returns an error.Trainer.TrainStep,Trainer.EvalStepandTrainer.Evalnow return errors as opposed to panicking.- Added
Trainer.WithDeviceAssignment. - Added
Trainer.DistributedTrainStep,Trainer.DistributedEvalStepandTrainer.DistributedEval.
- Added
- Package
datasets:- Added
datasets.DistributedAccumulator: converts a normalDatasetinto aDistributedDataset. - Added
datasets.OnDevice: pre-uploads data to devices.
- Added
- Package
backend:- Added
Backend.CopyToDevice Builder.Parameter()now takes an optionalShardingSpecfor sharded inputs.- Added ops:
AllReduce Backend.NumDevices()returns an int now.- Package
backends/notimplemented:- Added dummy
Backendthat can be used to easily mock backends.
- Added dummy
- Added
- Package
pkg/core/distributed:
-AddedDeviceMesh,ShardSpecanddistributed.Tensorobjects. - Package
pkg/core/tensors:- Added
Tensor.CheckValid(),Tensor.Device(),Tensor.Backend() - Changing it to return an error (as opposed to panic) where possible.
- Added
Other improvements:
- Package
simplego:- Cleanups and improvements: thanks to @wunderbarb!
- Fixed the issue with not handling the default value for the donate parameter in the Execute method.
- Package
cosineschedule:- Added
WarmUpStepsandNumCycleshyperparameters -- removed overloading ofperiodSteps.
- Added
- Added sponsorship badge and section to README.md. Also added the
FUNDING.ymlpointing to sponsorship. - Added
.golangci.ymland fixed many (still a long way to go) lint-warnings. - GitHub actions (workflows):
- Renamed tests to "Linux" and "Darwin."
- Updated badges in README.md.
- Updated dependency to Gopjrt v0.8.5, fixing xlabuilder for new C compilers.
- Removed
ui/fyneui:- It was incomplete, and it would be better offered as a separate package to avoid the dependencies.
- Package
graph:- Added a negative and out-of-bounds indices test for
Gather.
- Added a negative and out-of-bounds indices test for
- Package
simplego:- Partially fixed a race condition where the executable is finalized during the execution, causing crashes --
Thanks @ajroetker!
- Partially fixed a race condition where the executable is finalized during the execution, causing crashes --
v0.24.1: XLA (cpu) for Mac release
- Updated dependency to Gopjrt v0.8.4: added macOS (darwin/arm64) support and cpu PJRT plugin.
- Include
stablehlo(==xla) by default for MacOS in Darwin. - GitHub actions:
- Added macOS tests.
- Removed unnecessary
apt installof packages.
v0.24.0 🛠 **API change**: package tree restructured under `pkg`, `Exec` normalization; Backend `xla` now provided by `stablehlo`
This release breaks the API: mostly directory changes, so easy to fix.
Note: breaking the API is not done lightly (it always pains me). After 2 years of growing the project organically, with accumulating small API mistakes, it was time for a "freshen up".
- Highlights of this release:
- Deprecating old "xla" backend (now called "oldxla") in favor of "stablehlo" (aliased to "xla" as well):
in most cases nothing needs to be done (thegithub.com/gomlx/gomlx/backends/defaultwill replace one by the other automatically),
but in special cases there may require small changes. - Large refactoring: exported GoMLX packages moved under
/pkg. The following changes:- This requires changes to the import paths: core packages (
tensors,shapesandgraph) are underpkg/core;
machine learning packages (context,layers,train,datasets, ...) are underpkg/ml;
supporting packages (fsutil,sets,xslices,xsync) are underpkg/support. - Normalized
graph.Execandcontext.Execslightly changed the API:
theExec.Exec...methods now return an error, and theExec.MustExec...methods panic (instead of the oldExec.Callformat);
Thegraph.NewExecandcontext.NewExecreturn errors, and thegraph.MustNewExecandcontext.MustNewExecpanic. - File utilities under the old
ml/datanow are underpkg/support/fsutil, and the packageml/dataitself was
renamedpkg/ml/datasetsand now only holds the various datasets types. - Packages that were not moved:
- The
backendspackage: it will move to its own repository later in the year (or early 2026) - The
uiandexamplepackages: since they are just extras, we keep them where they are for now.
The coreGoMLXdoesn't depend on them, so we are more lax with their external dependencies.
- The
- This requires changes to the import paths: core packages (
- Deprecating old "xla" backend (now called "oldxla") in favor of "stablehlo" (aliased to "xla" as well):
- Copied external trivial
mustandexceptionspackages to/internal/..., to remove external dependencies. - Package
xla(the old one): now DEPRECATED and calledoldxla. The packagestablehloreplaces it, including aliasing thexlabackend name.- The old version is now registered as backend "oldxla".
- Only included in
github.com/gomlx/gomlx/backends/defaultif compiled with the tagoldxla.
- Package
stablehlo:- Now completely replacing
xlaby default. UsingGOMLX_BACKEND=xlawill actually use thestablehlobackend. - Added
github.com/gomlx/gomlx/backends/stablehlo/cpu/dynamicandgithub.com/gomlx/gomlx/backends/stablehlo/cpu/static
to optionally force dynamic/static linking of the CPU PJRT plugin. - Disabled XLA logs by default by setting TF_CPP_MIN_LOG_LEVEL to 2 (errors level), if it is not already set.
- Now completely replacing
- Package
graph:NewExec,NewExecAnyExec,ExecOnceandExecOnceNnow return an error on failure.MustNewExec,MustNewExecAny,MustExec,MustExecOnceandMustExecOnceNpanic on failure.- Introduced
Exec[1-4]andMustExec[1-4]to execute the graph and return exactly 1-4 values. - If no seeds are given, initialize new random number generators with a cryptographically secure seed—on OSes that provide that.
- Improved
Exectests.
- Package
context:NewExec,NewExecAnyExec,ExecOnceandExecOnceNnow return an error on failure.MustNewExec,MustNewExecAny,MustExec,MustExecOnceandMustExecOnceNpanic on failure.- Introduced
Exec[1-4]andMustExec[1-4]to execute the graph and return exactly 1-4 values. - Improved documentation.
- Packages
pkg/support/...:- Generic supporting functionality that is not core to GoMLX, but that users may also find useful to interact with it
are now better (and hopefully more definitively) organized in packages underpkg/support/. The following packages were moved/created:xslices,xmaps,xsync: extensions to the corresponding standard packages.set: previously known as packagetypes/fsutil: file system handling utilities, previously indata.
- Generic supporting functionality that is not core to GoMLX, but that users may also find useful to interact with it
- Package
inceptionv3moved toexamples - Package
ui/commandline: fixed progressbar in GoNB notebooks. - Package
kan: fixedPiecewiseConstant*layers for inputs of rank 1. - Packages
downloaderandhuggingface: had been already deprecated for a while, now removed.
See https://github.com/gomlx/go-huggingface for a replacement. - Package
hdf5moved to underexamples/inceptionv3, for now the only example that uses it.
If you need this, please let us know, maybe we move it to under support, or move it to https://github.com/gomlx/go-huggingface. - Package
datarenamed todatasets; Split downloading functionality underexamples/downloader. - Package
commandline:- Progressbar now shows the median step duration.
- Updated and refreshed all notebooks, including the tutorial.