# m3rg-iitd/matscibert architecture

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

- Interactive diagram: https://gitdiagram.com/m3rg-iitd/matscibert
- Repository: https://github.com/m3rg-iitd/matscibert

## Overview

##### Project type and purpose
- This is an open-source NLP toolkit centering on MatSciBERT, a domain-specific BERT model for materials-science text mining.
- It provides:
- A pretraining pipeline to train/extend MatSciBERT
- A text-normalization utility
- Three fine-tuning pipelines:
– Abstract/label classification (“cls”)
– Named-entity recognition (“ner”)
– Relation classification (“relation_classification”)

##### High-level components
A. Core model & utilities
- normalize_text.py – text-normalization
- HuggingFace Transformers (AutoTokenizer, AutoModel)
- The MatSciBERT checkpoints on HuggingFace
B. Pretraining
- pretraining/ – scripts to prepare corpus (normalize_corpus.py) and launch matscibert_pre_train.py
C. Fine-tuning modules
1. cls/
– cls_baseline/ – PyTorch baseline code (dataloader, models, train.py)
– custom datasets (glass_non_glass)
– cls/model/ – any production scripts or artifacts
2. ner/
– ner_datasets.py, ner.py – code for NER experiments
– conlleval.py, run.sh for evaluation
– ner/models/ – sub-folders for each dataset/model variant (matscholar, sofc, sofc_slot)
3. relation_classification/
– rel_baseline/ – baseline code similarly structured to cls_baseline
– datasets/ – annotated corpora with .txt/.ann files
– model/ – run.sh to launch experiments
– relation_classification.py, run.sh

##### Relationships and data flow
1. Data sources (raw text, CSV, .ann, .txt)
→ normalization utility
→ tokenization (HuggingFace tokenizer)
→ MatSciBERT embeddings
→ task-specific data loader
→ task-specific model head (classification, sequence labeling, relation scorer)
→ evaluation scripts (conlleval, custom metrics)
2. Pretraining pipeline runs on a large materials corpus, produces the MatSciBERT weights that feed all fine-tuning modules.

##### Key architectural patterns & principles
- Modular separation: one folder per task, each with baseline implementation, data loader, model definitions, training script
- Reuse of core utilities: normalization + HuggingFace APIs shared by all tasks
- Clear “data → preprocess → model → evaluate” pipeline structure
- Configuration via environment.yaml or requirements.txt and run.sh scripts

##### Essential elements
- Shared utilities explicitly to illustrate code reuse
- Per-task baseline code and custom models to highlight extensibility
- Run.sh / environment.yaml / requirements.txt as the configuration/deployment layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        direction TB
        Raw_Class_Data["Classification Data\n(.csv, raw text)"]
        Raw_NER_Data["NER Corpora\n(.txt, .ann)"]
        Raw_RC_Data["Relation Corpora\n(.txt, .ann)"]
    end

    %% Core Utilities and Model
    Normalizer["Normalizer\n(normalize_text.py)"]:::core_utils
    Tokenizer["Tokenizer\n(HuggingFace AutoTokenizer)"]:::core_utils
    MatSciBERT["MatSciBERT\n(Core Model)"]:::core_model

    %% Pretraining Pipeline
    subgraph "Pretraining Pipeline"
        direction TB
        NormalizeCorpus["normalize_corpus.py"] 
        PreTrainScript["matscibert_pre_train.py"]
        PreTrainRun["run.sh"]
    end

    %% Classification Pipeline
    subgraph "Classification Pipeline" 
        direction TB
        CLS_Main["cls.py"] 
        CLS_Baseline["cls_baseline/"] 
        CLS_Dataloader["my_dataloader.py"] 
        CLS_Models["models.py"] 
        CLS_Dataset["glass_non_glass/"]
        CLS_Run["run.sh"]
        CLS_Eval["Classification Evaluation"]
    end

    %% NER Pipeline
    subgraph "NER Pipeline"
        direction TB
        NER_Main["ner.py"]
        NER_Datasets["ner_datasets.py"]
        NER_Run["run.sh"]
        Conlleval["conlleval.py"]
        subgraph "NER Models"
            direction TB
            Matscholar["matscholar/run.sh"]
            Sofc["sofc/run.sh"]
            SofcSlot["sofc_slot/run.sh"]
        end
        NER_Eval["NER Evaluation"]
    end

    %% Relation Classification Pipeline
    subgraph "Relation Pipeline"
        direction TB
        RC_Main["relation_classification.py"]
        RC_Run["run.sh"]
        RC_Baseline["rel_baseline/"]
        RC_Baseline_Train["train.py"]
        RC_Baseline_DL["my_dataloader.py"]
        RC_Baseline_PP["preprocess.py"]
        RC_Baseline_Models["models.py"]
        RC_Dataset["annotated-materials-syntheses/"]
        RC_Model_Run["model/run.sh"]
        RC_Eval["Relation Evaluation"]
    end

    %% Flows from data sources
    Raw_Class_Data -->|"raw text"| Normalizer
    Raw_NER_Data -->|"raw text"| Normalizer
    Raw_RC_Data -->|"raw text"| Normalizer

    Normalizer -->|"normalized text"| Tokenizer
    Tokenizer -->|"tokens"| MatSciBERT

    %% Pretraining flow
    NormalizeCorpus --> PreTrainScript
    PreTrainScript --> PreTrainRun
    PreTrainRun -->|"pretrained weights"| MatSciBERT

    %% Classification flow
    MatSciBERT -->|"embeddings"| CLS_Main
    CLS_Main --> CLS_Baseline
    CLS_Baseline --> CLS_Dataloader
    CLS_Baseline --> CLS_Models
    CLS_Dataloader --> CLS_Main
    CLS_Models --> CLS_Main
    CLS_Main --> CLS_Run
    CLS_Run --> CLS_Eval

    %% NER flow
    MatSciBERT -->|"embeddings"| NER_Main
    NER_Main --> NER_Datasets
    NER_Datasets --> NER_Main
    NER_Main --> NER_Run
    NER_Run --> Conlleval
    Conlleval --> NER_Eval
    NER_Run --> Matscholar
    NER_Run --> Sofc
    NER_Run --> SofcSlot

    %% Relation flow
    MatSciBERT -->|"embeddings"| RC_Main
    RC_Main --> RC_Baseline
    RC_Baseline --> RC_Baseline_Train
    RC_Baseline --> RC_Baseline_DL
    RC_Baseline --> RC_Baseline_PP
    RC_Baseline --> RC_Baseline_Models
    RC_Main --> RC_Run
    RC_Run --> RC_Model_Run
    RC_Model_Run --> RC_Eval

    %% Click Events
    click Normalizer "https://github.com/m3rg-iitd/matscibert/blob/main/normalize_text.py"
    click NormalizeCorpus "https://github.com/m3rg-iitd/matscibert/blob/main/pretraining/normalize_corpus.py"
    click PreTrainScript "https://github.com/m3rg-iitd/matscibert/blob/main/pretraining/matscibert_pre_train.py"
    click PreTrainRun "https://github.com/m3rg-iitd/matscibert/blob/main/pretraining/run.sh"
    click CLS_Main "https://github.com/m3rg-iitd/matscibert/blob/main/cls/cls.py"
    click CLS_Baseline "https://github.com/m3rg-iitd/matscibert/blob/main/cls/cls_baseline/train.py"
    click CLS_Dataloader "https://github.com/m3rg-iitd/matscibert/blob/main/cls/cls_baseline/my_dataloader.py"
    click CLS_Models "https://github.com/m3rg-iitd/matscibert/blob/main/cls/cls_baseline/my_models/models.py"
    click CLS_Dataset "https://github.com/m3rg-iitd/matscibert/tree/main/cls/datasets/glass_non_glass/"
    click CLS_Run "https://github.com/m3rg-iitd/matscibert/blob/main/cls/run.sh"
    click NER_Main "https://github.com/m3rg-iitd/matscibert/blob/main/ner/ner.py"
    click NER_Datasets "https://github.com/m3rg-iitd/matscibert/blob/main/ner/ner_datasets.py"
    click Conlleval "https://github.com/m3rg-iitd/matscibert/blob/main/ner/conlleval.py"
    click NER_Run "https://github.com/m3rg-iitd/matscibert/blob/main/ner/run.sh"
    click Matscholar "https://github.com/m3rg-iitd/matscibert/blob/main/ner/models/matscholar/run.sh"
    click Sofc "https://github.com/m3rg-iitd/matscibert/blob/main/ner/models/sofc/run.sh"
    click SofcSlot "https://github.com/m3rg-iitd/matscibert/blob/main/ner/models/sofc_slot/run.sh"
    click RC_Main "https://github.com/m3rg-iitd/matscibert/blob/main/relation_classification/relation_classification.py"
    click RC_Run "https://github.com/m3rg-iitd/matscibert/blob/main/relation_classification/run.sh"
    click RC_Baseline_Train "https://github.com/m3rg-iitd/matscibert/blob/main/relation_classification/rel_baseline/train.py"
    click RC_Baseline_DL "https://github.com/m3rg-iitd/matscibert/blob/main/relation_classification/rel_baseline/my_dataloader.py"
    click RC_Baseline_PP "https://github.com/m3rg-iitd/matscibert/blob/main/relation_classification/rel_baseline/preprocess.py"
    click RC_Baseline_Models "https://github.com/m3rg-iitd/matscibert/blob/main/relation_classification/rel_baseline/my_models/models.py"
    click RC_Dataset "https://github.com/m3rg-iitd/matscibert/tree/main/relation_classification/datasets/annotated-materials-syntheses/"
    click RC_Model_Run "https://github.com/m3rg-iitd/matscibert/blob/main/relation_classification/model/run.sh"

    %% Styles
    classDef core_utils fill:#D0E6FF,stroke:#0066CC,color:#000
    classDef core_model fill:#FFD0D0,stroke:#CC0000,color:#000
    classDef pipeline fill:#DFFFD0,stroke:#00AA00,color:#000
    class Normalizer,Tokenizer core_utils
    class MatSciBERT core_model
    class CLS_Main,CLS_Baseline,CLS_Dataloader,CLS_Models,CLS_Run,NER_Main,NER_Datasets,NER_Run,Conlleval,Matscholar,Sofc,SofcSlot,RC_Main,RC_Run,RC_Baseline,RC_Baseline_Train,RC_Baseline_DL,RC_Baseline_PP,RC_Baseline_Models,RC_Model_Run pipeline
```
