diff --git a/CHANGELOG.md b/CHANGELOG.md index 11127be9..d04ab82f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,9 +40,9 @@ refers to `DeterministicGlobalWorkspace`. # 0.5.0 * Replace loss coef buffers by a `LossCoef` TypedDict. * Add - [`RepeatedDataset`](https://bdvllrs.github.io/shimmer/shimmer/dataset.html#RepeatedDataset) + [`RepeatedDataset`](https://ruflab.github.io/shimmer/shimmer/dataset.html#RepeatedDataset) to shimmer. -* Add docs in `docs/`, API documentation in https://bdvllrs.github.io/shimmer/, and +* Add docs in `docs/`, API documentation in https://ruflab.github.io/shimmer/, and some code examples. * Replace Black, isort, and flake8 with Ruff (see https://github.com/bdvllrs/shimmer/pull/8). @@ -65,9 +65,9 @@ refers to `DeterministicGlobalWorkspace`. * Rename all "with_uncertainty" methods to "bayesian". Note, BayesianGlobalWorkspaces are still a work in progress. * Added selection mechanisms (inheriting from `SelectionBase`, [see - docs](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/selection.html#SelectionBase)) + docs](https://ruflab.github.io/shimmer/latest/shimmer/modules/selection.html#SelectionBase)) to fuse representations according to different mechanisms (e.g. Attention). * `GlobalWorkspace` (and associated `GWModule`, `GWLosses`, ...) now uses the - [`RandomSelection`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/selection.html#RandomSelection) + [`RandomSelection`](https://ruflab.github.io/shimmer/latest/shimmer/modules/selection.html#RandomSelection) mechanism. For the old behavior, use - [`GlobalWorkspace2Domains`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspace2Domains). + [`GlobalWorkspace2Domains`](https://ruflab.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspace2Domains). diff --git a/README.md b/README.md index 3b827bfb..8a11dd5e 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,8 @@ This repository is the barebones API to build a global workspace. ## Install See [Installation instructions](docs/installation.md). -## Examples -You can find code examples in the `examples` folder. Each subfolder is a different -example. +## Example +You can find a code example in the `examples` folder. ## Tutorial You can also follow a tutorial on the basics of shimmer [here](docs/shimmer_basics.md). @@ -17,7 +16,7 @@ You can also find some additional information in the [Q&A](docs/q_and_a.md). ## API Documentation The full API documentation is available here: -[https://bdvllrs.github.io/shimmer/](https://bdvllrs.github.io/shimmer/). +[https://ruflab.github.io/shimmer/](https://ruflab.github.io/shimmer/). # Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/docs/q_and_a.md b/docs/q_and_a.md index 06105ede..a396f793 100644 --- a/docs/q_and_a.md +++ b/docs/q_and_a.md @@ -1,7 +1,7 @@ # Q&A ## How can I customize my GlobalWorkspace -[`GlobalWorkspaceBase`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspaceBase) +[`GlobalWorkspaceBase`](https://ruflab.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspaceBase) is a very generic implementation of the global workspace and uses different building blocks (given as arguments) to function: * **gw_mod**: a class implementation of `GWModuleBase` which defines how to encode, @@ -14,22 +14,22 @@ Different implementations have been made to initialize the Global Workspace more but you may need to implement a new one if you have very specific needs. To get insipiration, you can look at the source code of -[`GlobalWorkspace`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspace). +[`GlobalWorkspace`](https://ruflab.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspace). ## How can I change the loss function? If you are using pre-made GW architecture -([`GlobalWorkspace`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspace), -[`GlobalWorkspaceBayesian`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspaceBayesian), -[`GlobalWorkspaceFusion`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspaceFusion)) and want to update the loss +([`GlobalWorkspace`](https://ruflab.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspace), +[`GlobalWorkspaceBayesian`](https://ruflab.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspaceBayesian), +[`GlobalWorkspaceFusion`](https://ruflab.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspaceFusion)) and want to update the loss used for demi-cycles, cycles, translations or broadcast, you can do so directly from your definition of the -[`DomainModule`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule.compute_loss) +[`DomainModule`](https://ruflab.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule.compute_loss) when defining the `compute_loss` method. You also can have different losses for demi-cycles, cycles, ... by implementing the corresponding methods -([`compute_dcy_loss`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule.compute_dcy_loss), -[`compute_tr_loss`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule.compute_tr_loss), ...). +([`compute_dcy_loss`](https://ruflab.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule.compute_dcy_loss), +[`compute_tr_loss`](https://ruflab.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule.compute_tr_loss), ...). You can use your own contrastive loss function by passing it as an argument to the `GlobalWorkspace` class with the `contrastive_loss` loss argument. @@ -37,9 +37,9 @@ You can use your own contrastive loss function by passing it as an argument to t If you have more specific needs, like change how the different loss interact, or completely replace the loss combination we provide, you will need to implement a new Loss Module inheriting from -[`GWLossesBase`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/losses.html#GWLossesBase). +[`GWLossesBase`](https://ruflab.github.io/shimmer/latest/shimmer/modules/losses.html#GWLossesBase). Then, you can create a new implementation of -[`GlobalWorkspaceBase`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspaceBase) +[`GlobalWorkspaceBase`](https://ruflab.github.io/shimmer/latest/shimmer/modules/global_workspace.html#GlobalWorkspaceBase) (see section "How can I customize my GlobalWorkspace" for more details.) diff --git a/docs/shimmer_basics.md b/docs/shimmer_basics.md index 40b85bac..aaced901 100644 --- a/docs/shimmer_basics.md +++ b/docs/shimmer_basics.md @@ -13,7 +13,7 @@ to make a GW in shimmer: ![architecture](assets/shimmer_architecture.png) Let's detail: -- [`DomainModule`](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule)s +- [`DomainModule`](https://ruflab.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule)s are the individual domain modules which encode domain data into a latent vector; - the `GWModule` has access to the domain modules, and defines how to encode, decode and merge representations of the domains into a unique GW representation. - finally `GlobalWorkspaceBase` takes all building blocks to make a [Pytorch Lightning](https://lightning.ai/docs/pytorch/stable/) module @@ -87,7 +87,7 @@ class DomainDataModule(LightningDataModule): Now that our data module is defined, let's create `DomainModule`s. ## `DomainModule` -For more details about DomainModules, see the [DomainModule API docs](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule). +For more details about DomainModules, see the [DomainModule API docs](https://ruflab.github.io/shimmer/latest/shimmer/modules/domain.html#DomainModule). The `DomainModule` class extends from a LightningModule and requires you to define some methods: @@ -422,7 +422,7 @@ class GenericDomain(DomainModule): return LossOutput(loss=F.mse_loss(pred, target)) ``` -To learn more about LossOutput, see [API docs](https://bdvllrs.github.io/shimmer/latest/shimmer/modules/domain.html#LossOutput). +To learn more about LossOutput, see [API docs](https://ruflab.github.io/shimmer/latest/shimmer/modules/domain.html#LossOutput). ## Let's make a GW!