{
"cells": [
{
"cell_type": "markdown",
"id": "78e51340-6309-4f17-a4d4-f32d66ff8aab",
"metadata": {},
"source": [
"(quimb-within-jax)=\n",
"\n",
"# Using `quimb` within `jax`, `flax` and `optax`\n",
"\n",
"`quimb` is designed (using [`autoray`](https://github.com/jcmgray/autoray)) to\n",
"handle many different array backends, including [`jax`](https://github.com/google/jax). If you put `jax` arrays in your tensors, then `quimb` will dispatch all operations to `jax` functions, and moreover tensor network algorithms can then be traced through in order to compute gradients, and/or jit-compiled.\n",
"\n",
"While quimb has its own optimizer interface (`TNOptimizer`) which uses `jax`\n",
"or other libraries within it to compute the gradients, it is also possible to instead use `quimb` *within other* optimization frameworks. Here we demonstrate this with:\n",
"\n",
"* [`flax`](https://github.com/google/flax) - a library for designing machine learning 'models', which is also compatible with [`netket`](https://github.com/netket/netket) for example, and\n",
"* [`optax`](https://github.com/deepmind/optax) - an optimization library for `jax` which can itself be jit-compiled.\n",
"\n",
"The resulting computation is then entirely jit-compiled, with `quimb` merely orchestrating the initial computational graph.\n",
"\n",
"Here'll we do a simple 1D MERA optimization on the Heisenberg model:"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "b14fcab6-ed46-44be-81be-70d513008d83",
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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",
"image/svg+xml": [
""
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"import quimb.tensor as qtn\n",
"from quimb.experimental.merabuilder import MERA\n",
"\n",
"# our ansatz and hamiltonian\n",
"L = 16\n",
"psi = MERA.rand(L, D=8, seed=42, cyclic=False)\n",
"ham = qtn.ham_1d_heis(L)\n",
"\n",
"psi.draw(\n",
" color=[\"UNI\", \"ISO\"],\n",
" fix={psi.site_ind(i): (i, 0) for i in range(L)},\n",
")"
]
},
{
"cell_type": "markdown",
"id": "8df833dd-f4cb-424a-8dc3-59ff7a8ea55b",
"metadata": {},
"source": [
"As with `TNOptimizer`, we need a `loss_fn` which takes a tensor network and returns a scalar quantity to minimize. Often we also need a `norm_fn`, which first maps the tensor network into a constrained space (for example, with all unitary tensors):"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "b0aef4fb-1f1e-4151-b4dc-55efdd4d2c82",
"metadata": {},
"outputs": [],
"source": [
"def norm_fn(psi):\n",
" # parametrize our tensors as isometric/unitary\n",
" return psi.isometrize(method=\"cayley\")\n",
"\n",
"\n",
"def loss_fn(psi):\n",
" # compute the total energy, here quimb handles constructing\n",
" # and contracting all the appropriate lightcones\n",
" return psi.compute_local_expectation(ham)"
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "deff49b9-2dd0-4589-aa53-1d20a41f156f",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"-0.015578916803187806"
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# our initial energy:\n",
"loss_fn(norm_fn(psi))"
]
},
{
"cell_type": "markdown",
"id": "a8669a20-ac56-4c1f-8f66-78a9807a99ce",
"metadata": {},
"source": [
"Then we are ready to [construct our 'model' using `flax`](https://flax.readthedocs.io/en/latest/guides/setup_or_nncompact.html) (something very similar\n",
"can also be done [for e.g. `haiku` models](https://dm-haiku.readthedocs.io/en/latest/)):"
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "ed902d1f-7216-4f9e-b06e-e1bfd32e78c7",
"metadata": {},
"outputs": [],
"source": [
"import flax.linen as nn\n",
"import jax\n",
"import optax\n",
"\n",
"\n",
"class CustomModule(nn.Module):\n",
" def setup(self):\n",
" # strip out the initial raw arrays\n",
" params, skeleton = qtn.pack(psi)\n",
" # save the stripped 'skeleton' tn for use later\n",
" self.skeleton = skeleton\n",
"\n",
" # assign each array as a parameter to optimize\n",
" self.params = {\n",
" i: self.param(f\"param_{i}\", lambda _: data)\n",
" for i, data in params.items()\n",
" }\n",
"\n",
" def __call__(self):\n",
" psi = qtn.unpack(self.params, self.skeleton)\n",
" return loss_fn(norm_fn(psi))"
]
},
{
"cell_type": "markdown",
"id": "8db6982f-5e03-490a-9037-395ca8fb92c9",
"metadata": {},
"source": [
"Next we define a single, [jit-compiled, optimization step](https://optax.readthedocs.io/en/latest/optax-101.html):"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "ead44054-5981-4f59-a596-ba287eaf4beb",
"metadata": {},
"outputs": [],
"source": [
"# initialize our model and loss/gradient function\n",
"model = CustomModule()\n",
"params = model.init(jax.random.PRNGKey(42))\n",
"loss_grad_fn = jax.value_and_grad(model.apply)\n",
"\n",
"# initialize our optimizer\n",
"tx = optax.adabelief(learning_rate=0.01)\n",
"opt_state = tx.init(params)\n",
"\n",
"\n",
"@jax.jit\n",
"def step(params, opt_state):\n",
" # our step: compute the loss and gradient, and update the optimizer\n",
" loss, grads = loss_grad_fn(params)\n",
" updates, opt_state = tx.update(grads, opt_state, params)\n",
" params = optax.apply_updates(params, updates)\n",
" return params, opt_state, loss"
]
},
{
"cell_type": "markdown",
"id": "1699b7c0-5006-4ee1-a113-1a9f41709a86",
"metadata": {},
"source": [
"And now we are ready to optimize!"
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "ad95cc4d-c366-4508-b340-cd154a8bb48e",
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"-6.904621124267578: 100%|██████████| 1000/1000 [00:33<00:00, 29.88it/s] \n"
]
}
],
"source": [
"import tqdm\n",
"\n",
"its = 1_000\n",
"pbar = tqdm.tqdm(range(its))\n",
"\n",
"for _ in pbar:\n",
" params, opt_state, loss_val = step(params, opt_state)\n",
" pbar.set_description(f\"{loss_val}\")"
]
},
{
"cell_type": "markdown",
"id": "9f3a6fdd-1799-4fa2-ab93-f61d787aaead",
"metadata": {},
"source": [
"Finally if we want to insert the optimized raw parameters back into a tensor network then we can do so with:"
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "5bef5389-a7b4-478e-9629-d0e32f522d21",
"metadata": {},
"outputs": [],
"source": [
"mera_opt = psi.copy()\n",
"\n",
"# resinsert the raw, optimized arrays\n",
"for i, t in mera_opt.tensor_map.items():\n",
" t.modify(data=params[\"params\"][f\"param_{i}\"].__array__())\n",
"\n",
"# then we want the constrained form\n",
"mera_opt = norm_fn(mera_opt)"
]
},
{
"cell_type": "markdown",
"id": "99b82a57-7f83-4434-9af2-5b10d00c57b2",
"metadata": {},
"source": [
"Then we can check the energy outside of jax:"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "3d72eb5d-db64-4a2b-9264-c372c211279b",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"-6.90447020410412"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"loss_fn(mera_opt)"
]
},
{
"cell_type": "markdown",
"id": "b6f419f6-cf11-4453-8843-32e9766a122b",
"metadata": {},
"source": [
"and that the state is still unitary and thus normalized:"
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "9bae4435-9b39-4ece-859d-b51675f3b460",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"1.0000000242457867"
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"mera_opt.H @ mera_opt"
]
},
{
"cell_type": "markdown",
"id": "8264a073-e569-441d-8f53-bce2ff497b1e",
"metadata": {},
"source": [
"## Notes\n",
"\n",
"* `quimb` also registers all `Tensor` and `TensorNetwork` classes with jax's pytree system, so they can be used as directly input and output to functions such as `jax.grad` and `jax.jit`.\n",
"* `jax` by default converts everything to single precision (thus the deviation from 1.0 above), [see here about disabling this behavior](https://jax.readthedocs.io/en/latest/notebooks/Common_Gotchas_in_JAX.html#double-64bit-precision)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3"
},
"vscode": {
"interpreter": {
"hash": "39c10650315d977fb13868ea1402e99f3e10e9885c2c202e692ae90b8995050d"
}
}
},
"nbformat": 4,
"nbformat_minor": 2
}