# facebookresearch/muse architecture

> Architecture diagram of the GitHub repository facebookresearch/muse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/muse
- Repository: https://github.com/facebookresearch/muse

## Overview

MUSE aligns pretrained monolingual word embeddings into a shared multilingual space, either from bilingual/identical-string anchors or through adversarial training followed by dictionary-based Procrustes refinement. The main workflow loads embeddings, trains and refines a mapping, evaluates alignment quality, and optionally exports aligned vectors. README capabilities include word translation, word and sentence similarity/retrieval, and monolingual similarity and analogy evaluation. Some source excerpts are partial; uncertain internal wiring is omitted.

Main entry points: [`src/trainer.py`](https://github.com/facebookresearch/muse/blob/main/src/trainer.py) (Alignment trainer), [`supervised.py`](https://github.com/facebookresearch/muse/blob/main/supervised.py) (Supervised run), [`unsupervised.py`](https://github.com/facebookresearch/muse/blob/main/unsupervised.py) (Unsupervised run), [`src/evaluation/evaluator.py`](https://github.com/facebookresearch/muse/blob/main/src/evaluation/evaluator.py) (Evaluation coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and loading"]
  node_model["Embedding model<br/>[models.py]"]
  node_dictionary["Vocabulary index<br/>[dictionary.py]"]
end

subgraph group_alignment["Embedding alignment"]
  node_supervised["Supervised run<br/>[supervised.py]"]
  node_unsupervised["Unsupervised run<br/>[unsupervised.py]"]
  node_trainer["Alignment trainer<br/>[trainer.py]"]
  node_dico_builder["Induced dictionary<br/>[dico_builder.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluate_cli["Evaluation run<br/>[evaluate.py]"]
  node_evaluator["Evaluation coordinator<br/>[evaluator.py]"]
  node_wordsim["Similarity and analogy<br/>[wordsim.py]"]
  node_word_translation["Word retrieval"]
  node_sent_translation["Sentence retrieval"]
end

subgraph group_support["Shared runtime"]
  node_utils["Runtime utilities<br/>[utils.py]"]
  node_logger["Experiment logging<br/>[logger.py]"]
end

node_user(("Researcher"))
node_vectors["Pretrained vectors"]
node_anchors["Bilingual anchors"]
node_export["Aligned vectors"]
node_eval_data["Evaluation datasets"]

node_user -->|"starts"| node_supervised
node_user -->|"starts"| node_unsupervised
node_user -->|"starts"| node_evaluate_cli
node_vectors -->|"loads"| node_model
node_supervised -->|"builds"| node_model
node_unsupervised -->|"builds"| node_model
node_evaluate_cli -->|"builds"| node_model
node_model -->|"indexes"| node_dictionary
node_supervised -->|"creates"| node_trainer
node_unsupervised -->|"creates"| node_trainer
node_evaluate_cli -->|"creates"| node_trainer
node_anchors -->|"supplies pairs"| node_trainer
node_trainer -->|"induces pairs"| node_dico_builder
node_supervised -->|"refines mapping"| node_trainer
node_unsupervised -->|"trains and refines"| node_trainer
node_trainer -->|"exports vectors"| node_export
node_supervised -->|"evaluates"| node_evaluator
node_unsupervised -->|"evaluates"| node_evaluator
node_evaluate_cli -->|"evaluates"| node_evaluator
node_evaluator -->|"scores similarity"| node_wordsim
node_evaluator -->|"scores retrieval"| node_word_translation
node_evaluator -->|"scores retrieval"| node_sent_translation
node_wordsim -->|"reads tasks"| node_eval_data
node_word_translation -->|"reads dictionaries"| node_eval_data
node_sent_translation -->|"reads Europarl"| node_eval_data
node_supervised -->|"initializes runtime"| node_utils
node_unsupervised -->|"initializes runtime"| node_utils
node_evaluate_cli -->|"initializes runtime"| node_utils
node_utils -->|"creates logger"| node_logger
node_supervised -->|"logs progress"| node_logger
node_unsupervised -->|"logs progress"| node_logger
node_evaluator -->|"logs scores"| node_logger

click node_supervised "https://github.com/facebookresearch/muse/blob/main/supervised.py"
click node_unsupervised "https://github.com/facebookresearch/muse/blob/main/unsupervised.py"
click node_evaluate_cli "https://github.com/facebookresearch/muse/blob/main/evaluate.py"
click node_model "https://github.com/facebookresearch/muse/blob/main/src/models.py"
click node_dictionary "https://github.com/facebookresearch/muse/blob/main/src/dictionary.py"
click node_trainer "https://github.com/facebookresearch/muse/blob/main/src/trainer.py"
click node_dico_builder "https://github.com/facebookresearch/muse/blob/main/src/dico_builder.py"
click node_evaluator "https://github.com/facebookresearch/muse/blob/main/src/evaluation/evaluator.py"
click node_wordsim "https://github.com/facebookresearch/muse/blob/main/src/evaluation/wordsim.py"
click node_word_translation "https://github.com/facebookresearch/muse/blob/main/src/evaluation/word_translation.py"
click node_sent_translation "https://github.com/facebookresearch/muse/blob/main/src/evaluation/sent_translation.py"
click node_eval_data "https://github.com/facebookresearch/muse/tree/main/data"
click node_utils "https://github.com/facebookresearch/muse/blob/main/src/utils.py"
click node_logger "https://github.com/facebookresearch/muse/blob/main/src/logger.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_model,node_dictionary toneBlue
class node_supervised,node_unsupervised,node_trainer,node_dico_builder toneAmber
class node_evaluate_cli,node_evaluator,node_wordsim,node_word_translation,node_sent_translation toneMint
class node_utils,node_logger toneRose
class node_user,node_vectors,node_anchors,node_export toneIndigo
class node_eval_data toneTeal
```

## Components

### Inputs and loading

- [Embedding model](https://github.com/facebookresearch/muse/blob/main/src/models.py): `src/models.py`
- [Vocabulary index](https://github.com/facebookresearch/muse/blob/main/src/dictionary.py): `src/dictionary.py`

### Embedding alignment

- [Supervised run](https://github.com/facebookresearch/muse/blob/main/supervised.py): `supervised.py`
- [Unsupervised run](https://github.com/facebookresearch/muse/blob/main/unsupervised.py): `unsupervised.py`
- [Alignment trainer](https://github.com/facebookresearch/muse/blob/main/src/trainer.py): `src/trainer.py`
- [Induced dictionary](https://github.com/facebookresearch/muse/blob/main/src/dico_builder.py): `src/dico_builder.py`

### Evaluation

- [Evaluation run](https://github.com/facebookresearch/muse/blob/main/evaluate.py): `evaluate.py`
- [Evaluation coordinator](https://github.com/facebookresearch/muse/blob/main/src/evaluation/evaluator.py): `src/evaluation/evaluator.py`
- [Similarity and analogy](https://github.com/facebookresearch/muse/blob/main/src/evaluation/wordsim.py): `src/evaluation/wordsim.py`
- [Word retrieval](https://github.com/facebookresearch/muse/blob/main/src/evaluation/word_translation.py): `src/evaluation/word_translation.py`
- [Sentence retrieval](https://github.com/facebookresearch/muse/blob/main/src/evaluation/sent_translation.py): `src/evaluation/sent_translation.py`

### Shared runtime

- [Runtime utilities](https://github.com/facebookresearch/muse/blob/main/src/utils.py): `src/utils.py`
- [Experiment logging](https://github.com/facebookresearch/muse/blob/main/src/logger.py): `src/logger.py`

### Other components

- **Researcher**
- **Pretrained vectors**
- **Bilingual anchors**
- **Aligned vectors**
- [Evaluation datasets](https://github.com/facebookresearch/muse/tree/main/data): `data`

## Connections

- Researcher → Supervised run: starts
- Researcher → Unsupervised run: starts
- Researcher → Evaluation run: starts
- Pretrained vectors → Embedding model: loads
- Supervised run → Embedding model: builds
- Unsupervised run → Embedding model: builds
- Evaluation run → Embedding model: builds
- Embedding model → Vocabulary index: indexes
- Supervised run → Alignment trainer: creates
- Unsupervised run → Alignment trainer: creates
- Evaluation run → Alignment trainer: creates
- Bilingual anchors → Alignment trainer: supplies pairs
- Alignment trainer → Induced dictionary: induces pairs
- Supervised run → Alignment trainer: refines mapping
- Unsupervised run → Alignment trainer: trains and refines
- Alignment trainer → Aligned vectors: exports vectors
- Supervised run → Evaluation coordinator: evaluates
- Unsupervised run → Evaluation coordinator: evaluates
- Evaluation run → Evaluation coordinator: evaluates
- Evaluation coordinator → Similarity and analogy: scores similarity
- Evaluation coordinator → Word retrieval: scores retrieval
- Evaluation coordinator → Sentence retrieval: scores retrieval
- Similarity and analogy → Evaluation datasets: reads tasks
- Word retrieval → Evaluation datasets: reads dictionaries
- Sentence retrieval → Evaluation datasets: reads Europarl
- Supervised run → Runtime utilities: initializes runtime
- Unsupervised run → Runtime utilities: initializes runtime
- Evaluation run → Runtime utilities: initializes runtime
- Runtime utilities → Experiment logging: creates logger
- Supervised run → Experiment logging: logs progress
- Unsupervised run → Experiment logging: logs progress
- Evaluation coordinator → Experiment logging: logs scores