FahimehBahman commited on
Commit
e62a04f
Β·
verified Β·
1 Parent(s): b64e943

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +240 -198
README.md CHANGED
@@ -18,13 +18,17 @@ tags:
18
 
19
  **PolyTAO Student** is a property-conditioned Transformer model developed as part of my M.Sc. thesis, **β€œKnowledge-Distilled Transformers for Property-Conditioned Polymer Generation.”**
20
 
21
- The project investigates whether smaller Transformer models can retain useful generative behavior after knowledge distillation from a larger property-conditioned teacher model.
22
 
23
- The teacher was initialized from the publicly available **`hkqiu/PolyTAO-BigSMILES_Version`** checkpoint and subsequently trained with molecular-property conditioning. The trained teacher was then frozen and used for feature-level knowledge distillation into smaller student architectures.
24
 
25
- Multiple student capacities were investigated by reducing the number of encoder and decoder layers while keeping the main Transformer configuration consistent.
26
 
27
- The checkpoint published in this repository corresponds to the **20% student capacity configuration**.
 
 
 
 
28
 
29
  > **Research model:** This checkpoint is provided for research and reproducibility purposes. It is not intended for production use or for making chemical or experimental decisions.
30
 
@@ -34,37 +38,33 @@ The checkpoint published in this repository corresponds to the **20% student cap
34
 
35
  The central research question behind PolyTAO is:
36
 
37
- > **How does reducing Transformer model capacity affect the quality, chemical validity, and property fidelity of generated polymers?**
38
 
39
- Rather than training only one compressed model, the research evaluates multiple student capacities to investigate the trade-off between model compression and generative behavior.
40
 
41
- The work focuses particularly on whether knowledge distilled from a larger Transformer can preserve useful molecular-property information when the depth of the student architecture is substantially reduced.
42
 
43
  ---
44
 
45
  ## Model Lineage
46
 
47
- The model development pipeline can be summarized as:
48
 
49
  ```text
50
  hkqiu/PolyTAO-BigSMILES_Version
51
  β”‚
52
  β–Ό
53
  Property-Conditioned Teacher
 
54
  β”‚
55
  β”‚ Feature-Level
56
  β”‚ Knowledge Distillation
57
  β–Ό
58
  PolyTAO Students
59
  β”‚
60
- β”Œβ”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”
61
- β–Ό β–Ό β–Ό
62
- larger medium smaller
63
- students students students
64
- β”‚
65
  β–Ό
66
- Capacity–Performance
67
- Evaluation
68
  ```
69
 
70
  The publicly available `hkqiu/PolyTAO-BigSMILES_Version` checkpoint therefore serves as the starting point for the teacher model rather than being the final student model itself.
@@ -75,13 +75,13 @@ The publicly available `hkqiu/PolyTAO-BigSMILES_Version` checkpoint therefore se
75
 
76
  The PolyTAO teacher is based on a **T5-style encoder-decoder Transformer architecture**.
77
 
78
- The teacher was initialized using:
79
 
80
  ```text
81
  hkqiu/PolyTAO-BigSMILES_Version
82
  ```
83
 
84
- and loaded using Hugging Face Transformers.
85
 
86
  The teacher architecture contains:
87
 
@@ -91,14 +91,16 @@ Decoder layers: 12
91
  d_model: 768
92
  ```
93
 
94
- A custom property-conditioning mechanism was added to the model.
95
 
96
- The teacher receives both:
97
 
98
  1. a tokenized polymer representation, and
99
  2. a 15-dimensional molecular-property vector.
100
 
101
- The property vector is mapped into the Transformer's hidden space using a learned linear projection:
 
 
102
 
103
  ```text
104
  15 Molecular Properties
@@ -115,56 +117,52 @@ Normalized Property Embedding
115
  β–Ό
116
  Property-Conditioned
117
  Encoder Representation
 
 
 
118
  ```
119
 
120
- The property embedding is added to the encoder hidden states before decoding.
121
 
122
- After training, the Transformer checkpoint, tokenizer, and learned property projection are saved separately.
123
 
124
  ---
125
 
126
- ## Student Architecture
127
 
128
- Student models are constructed from the teacher configuration while reducing the number of encoder and decoder layers.
129
 
130
- Student depth is calculated as:
131
 
132
- ```text
133
- student_layers = max(
134
- 1,
135
- round(teacher_layers Γ— capacity / 100)
136
- )
137
- ```
138
-
139
- The main Transformer configuration is otherwise kept consistent so that the effect of reducing model depth can be investigated more directly.
140
-
141
- The student Transformer is initialized independently rather than directly copying the trained teacher weights.
142
 
143
- Knowledge is subsequently transferred from the frozen teacher during student training.
144
 
145
- ### Published Checkpoint
146
-
147
- The checkpoint published in this repository corresponds to:
148
 
149
  ```text
150
- Student capacity: 20%
151
-
152
- Teacher encoder layers: 12
153
- Student encoder layers: 2
154
-
155
- Teacher decoder layers: 12
156
- Student decoder layers: 2
157
  ```
158
 
159
- This represents an aggressive reduction in Transformer depth and is used to study how much useful generative behavior can be retained through knowledge distillation.
 
 
160
 
161
  ---
162
 
163
  ## Property Conditioning
164
 
165
- Both teacher and student models use the same property-conditioning mechanism.
166
 
167
- Generation is conditioned on **15 molecular properties**:
168
 
169
  1. `MolWt`
170
  2. `HeavyAtomCount`
@@ -184,106 +182,110 @@ Generation is conditioned on **15 molecular properties**:
184
 
185
  During preprocessing, normalized versions of these properties are used when available.
186
 
187
- The property vector is projected into the Transformer hidden space:
188
 
189
  ```text
190
- Property Vector (15 dimensions)
191
- β”‚
192
- β–Ό
193
- Linear Projection
194
- β”‚
195
- β–Ό
196
- L2 Normalization
197
- β”‚
198
- β–Ό
199
- Property Scaling
200
- β”‚
201
- β–Ό
202
- Property Embedding
203
- β”‚
204
- β–Ό
205
- Encoder Hidden States
206
- β”‚
207
- β–Ό
208
- Conditioned Representation
 
 
209
  ```
210
 
211
  The property embedding is scaled before being added to the encoder representation.
212
 
213
- The training configuration uses:
214
 
215
  ```text
216
  Property scale = 0.05
217
  ```
218
 
 
 
 
 
 
 
219
  ---
220
 
221
  ## Knowledge Distillation
222
 
223
  The student is trained using a frozen property-conditioned teacher.
224
 
225
- For each training sample, both models receive the same tokenized polymer representation and molecular-property vector.
226
 
227
- The teacher generates conditioned encoder hidden representations.
228
 
229
- The student simultaneously learns:
230
 
231
  - the sequence-generation task, and
232
  - the internal representation produced by the teacher.
233
 
234
  ### Sequence Generation Loss
235
 
236
- The student is trained using the standard sequence-to-sequence cross-entropy loss.
237
-
238
- ### Feature-Level Knowledge Distillation
239
 
240
- The conditioned encoder representation produced by the student is compared with the corresponding teacher representation.
241
 
242
- Mean Squared Error (MSE) is used for the feature-level distillation objective.
243
 
244
  Conceptually:
245
 
246
  ```text
247
- Teacher
248
- β”‚
249
- β–Ό
250
- Conditioned Teacher Hidden States
251
- β”‚
252
- β”‚
253
- β”‚ MSE
254
- β”‚
255
- β–Ό
256
- Conditioned Student Hidden States
257
- β–²
258
- β”‚
259
- Student
260
  ```
261
 
262
- The training objective combines the sequence-generation and knowledge-distillation objectives.
263
-
264
- Conceptually:
265
 
266
  ```text
267
  Total Loss
268
  =
269
- Sequence Generation Loss
270
  +
271
- Ξ± Γ— Knowledge Distillation Loss
272
  ```
273
 
274
- with:
275
 
276
  ```text
277
  Ξ± = 0.5
278
  ```
279
 
280
- During student training, the teacher remains frozen.
281
 
282
  ---
283
 
284
  ## Training Configuration
285
 
286
- ### Teacher
287
 
288
  The teacher training configuration includes:
289
 
@@ -298,13 +300,13 @@ The teacher training configuration includes:
298
  | Validation ratio | `0.1` |
299
  | Precision | `32-bit` |
300
 
301
- The teacher is trained using PyTorch Lightning.
302
 
303
- Training and validation losses are logged during training.
304
 
305
  ---
306
 
307
- ### Student
308
 
309
  The student training configuration includes:
310
 
@@ -318,7 +320,6 @@ The student training configuration includes:
318
  | Property scale | `0.05` |
319
  | Validation ratio | `0.1` |
320
  | Random seed | `42` |
321
- | Precision | `32-bit` |
322
 
323
  The implementation uses:
324
 
@@ -326,12 +327,7 @@ The implementation uses:
326
  - PyTorch Lightning
327
  - Hugging Face Transformers
328
 
329
- Training logs include:
330
-
331
- - total training loss
332
- - cross-entropy loss
333
- - knowledge-distillation loss
334
- - validation loss
335
 
336
  ---
337
 
@@ -339,9 +335,9 @@ Training logs include:
339
 
340
  The research dataset was derived from the **Open Macromolecular Genome (OMG)** polymer dataset.
341
 
342
- The experimental dataset contains approximately **99,000 polymer samples**, where each sample contains a polymer representation together with molecular-property information.
343
 
344
- The preprocessing pipeline includes:
345
 
346
  ```text
347
  Raw Polymer Data
@@ -362,30 +358,30 @@ Polymer Tokenization
362
  Model Input
363
  ```
364
 
365
- The molecular descriptors used for conditioning and evaluation are calculated using **RDKit**.
366
 
367
- The dataset itself is **not distributed in this model repository**.
368
 
369
  ---
370
 
371
  ## Evaluation
372
 
373
- The generated polymer representations are evaluated using several complementary metrics.
374
 
375
- Evaluation considers both:
376
 
377
  1. whether generated structures are chemically valid according to RDKit, and
378
- 2. whether the molecular properties of valid generated structures agree with the requested property conditions.
379
 
380
  ---
381
 
382
  ## Chemical Validity
383
 
384
- Generated sequences are cleaned and subsequently parsed and sanitized using RDKit.
385
 
386
- A generated structure is counted as valid only when RDKit can successfully construct and sanitize the molecule.
387
 
388
- For the final evaluation of the **20% student configuration** published here:
389
 
390
  | Metric | Result |
391
  |---|---:|
@@ -393,7 +389,7 @@ For the final evaluation of the **20% student configuration** published here:
393
  | Valid samples | 250 |
394
  | **Chemical validity** | **50.0%** |
395
 
396
- Only valid generated structures are included in downstream molecular-property evaluation.
397
 
398
  ---
399
 
@@ -401,37 +397,35 @@ Only valid generated structures are included in downstream molecular-property ev
401
 
402
  For valid generated structures, the 15 molecular properties are recalculated using RDKit.
403
 
404
- Generated properties are then compared with the corresponding conditioning targets.
405
-
406
- The evaluation uses four complementary metrics.
407
 
408
  ### Mean Absolute Error β€” MAE
409
 
410
- Measures the average absolute difference between generated and target property values.
411
 
412
  Lower values indicate smaller average errors.
413
 
414
  ### Root Mean Squared Error β€” RMSE
415
 
416
- Measures prediction error while giving greater weight to larger deviations.
417
 
418
  Lower values indicate smaller errors.
419
 
420
  ### Pearson Correlation
421
 
422
- Measures the linear relationship between generated and target property values.
423
 
424
  Higher positive correlation indicates stronger agreement between changes in the target property and changes in the generated property.
425
 
426
  ### Maximum Mean Discrepancy β€” MMD
427
 
428
- MMD compares the distributions of generated and target property values using an RBF kernel.
429
 
430
- Lower MMD indicates closer distributional agreement.
431
 
432
- However, MMD should **not be interpreted in isolation**.
433
 
434
- A low MMD value does not necessarily imply superior generative performance. A compressed model may, for example, generate less diverse or structurally simpler outputs whose aggregate property distributions happen to resemble the target distribution.
435
 
436
  For this reason, MMD is interpreted jointly with:
437
 
@@ -445,7 +439,7 @@ For this reason, MMD is interpreted jointly with:
445
 
446
  ## Distribution Analysis
447
 
448
- Selected molecular-property distributions can be visualized by comparing valid generated samples with the corresponding reference distribution.
449
 
450
  ### Molecular Weight
451
 
@@ -459,11 +453,13 @@ Selected molecular-property distributions can be visualized by comparing valid g
459
 
460
  ![Generated vs Test β€” Ring Count](RingCount_hist.png)
461
 
462
- These plots complement the numerical metrics and help illustrate whether the generated structures reproduce important aspects of the target property distributions.
 
 
463
 
464
  ---
465
 
466
- ## Complete Experimental Pipeline
467
 
468
  ```text
469
  Open Macromolecular Genome
@@ -480,7 +476,6 @@ Open Macromolecular Genome
480
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
481
  β”‚
482
  β–Ό
483
- Base Transformer Model
484
  hkqiu/PolyTAO-BigSMILES_Version
485
  β”‚
486
  β–Ό
@@ -490,6 +485,7 @@ hkqiu/PolyTAO-BigSMILES_Version
490
  Teacher Hidden States
491
  β”‚
492
  β”‚
 
493
  β”‚ Knowledge Distillation
494
  β–Ό
495
  Property-Conditioned Student
@@ -504,15 +500,15 @@ hkqiu/PolyTAO-BigSMILES_Version
504
  Valid Generated Structures
505
  β”‚
506
  β–Ό
507
- RDKit Property Recalculation
508
  β”‚
509
  β–Ό
510
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
 
511
  β”‚ MAE β”‚
512
  β”‚ RMSE β”‚
513
  β”‚ MMD β”‚
514
  β”‚ Pearson Correlation β”‚
515
- β”‚ Chemical Validity β”‚
516
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
517
  β”‚
518
  β–Ό
@@ -522,19 +518,29 @@ hkqiu/PolyTAO-BigSMILES_Version
522
 
523
  ---
524
 
525
- ## Model Files
526
 
527
- The complete property-conditioned student model requires more than the standard Transformer checkpoint.
528
-
529
- The model repository may contain files such as:
530
 
531
  ```text
532
- config.json
533
- generation_config.json
534
- model.safetensors
535
- tokenizer_config.json
536
- tokenizer files
537
- property_proj_student.pt
 
 
 
 
 
 
 
 
 
 
 
 
538
  ```
539
 
540
  The standard Transformer weights are stored in:
@@ -543,35 +549,64 @@ The standard Transformer weights are stored in:
543
  model.safetensors
544
  ```
545
 
546
- The learned property-conditioning projection is stored separately in:
547
 
548
  ```text
549
  property_proj_student.pt
550
  ```
551
 
552
- This projection maps the 15-dimensional molecular-property vector into the Transformer hidden space.
553
 
554
- Because the property-conditioning mechanism is implemented outside the standard T5 forward interface, loading only the Transformer checkpoint is **not sufficient to reproduce property-conditioned generation**.
555
 
556
  ---
557
 
558
- ## Usage
 
 
 
 
 
 
 
 
 
 
 
559
 
560
- This model requires a custom property-conditioning step.
 
 
 
561
 
562
- It should therefore not be treated as a standard text-to-text T5 model that can reproduce the research pipeline using only a generic Hugging Face `pipeline()` call.
563
 
564
- The basic loading procedure is:
 
 
 
 
 
 
 
 
 
 
 
 
565
 
566
  ```python
567
  import torch
568
  import torch.nn as nn
569
 
 
570
  from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
571
 
572
  MODEL_ID = "FahimehBahman/PolyTAO-Student"
573
 
574
- device = "cuda" if torch.cuda.is_available() else "cpu"
 
 
575
 
576
  tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
577
 
@@ -585,50 +620,54 @@ property_proj = nn.Linear(
585
  15,
586
  model.config.d_model
587
  ).to(device)
588
- ```
589
 
590
- The learned weights from:
 
 
 
 
 
 
 
 
591
 
592
- ```text
593
- property_proj_student.pt
594
  ```
595
 
596
- must then be loaded into `property_proj`.
597
-
598
- Property-conditioned generation requires the following steps:
599
 
600
  ```text
601
- Polymer Input
602
- β”‚
603
- β–Ό
604
- Tokenization
605
- β”‚
606
- β–Ό
607
- Transformer Encoder
608
- β”‚
609
- β–Ό
610
- Encoder Hidden States
611
- β–²
612
- β”‚
613
- 15 Molecular Properties
614
- β”‚
615
- β–Ό
616
- Property Projection
617
- β”‚
618
- β–Ό
619
- Normalized Property Embedding
620
- β”‚
621
- β–Ό
622
  Conditioned Encoder Representation
623
- β”‚
624
- β–Ό
625
- Autoregressive Generation
626
- β”‚
627
- β–Ό
628
- Generated Polymer
629
  ```
630
 
631
- The complete training and evaluation implementation is provided in the accompanying PolyTAO source-code repository.
 
 
632
 
633
  ---
634
 
@@ -638,13 +677,13 @@ PolyTAO Student is intended primarily for research involving:
638
 
639
  - knowledge distillation
640
  - Transformer model compression
641
- - property-conditioned generation
642
  - polymer generative modeling
643
- - capacity–performance trade-offs
644
  - efficient generative Transformer architectures
 
645
  - evaluation of compressed generative models
646
 
647
- The checkpoint can also serve as a reproducible artifact for studying aggressive Transformer depth reduction under feature-level knowledge distillation.
648
 
649
  ---
650
 
@@ -658,10 +697,13 @@ This model has several important limitations.
658
  - Generated structures have not been experimentally validated.
659
  - RDKit-based validation is a computational validity check rather than experimental verification.
660
  - Property conditioning is limited to the molecular descriptors used during training.
 
661
  - Performance depends on preprocessing and decoding configuration.
 
662
  - Distributional similarity does not guarantee structural diversity.
663
- - MMD should not be interpreted independently of validity and other evaluation metrics.
664
- - Results from this model should not be used directly for safety-critical, medical, industrial, or experimental chemical decisions without independent expert validation.
 
665
 
666
  ---
667
 
@@ -671,7 +713,7 @@ PolyTAO was developed as part of the M.Sc. thesis:
671
 
672
  **Knowledge-Distilled Transformers for Property-Conditioned Polymer Generation**
673
 
674
- The research investigates the effect of Transformer capacity reduction on property-conditioned polymer generation.
675
 
676
  The work combines:
677
 
@@ -679,12 +721,12 @@ The work combines:
679
  - molecular-property conditioning
680
  - feature-level knowledge distillation
681
  - model compression
682
- - computational chemistry descriptors
683
  - systematic quantitative evaluation
684
 
685
- Multiple student configurations were trained and evaluated to investigate how model depth affects generative behavior and property fidelity.
686
 
687
- The published checkpoint represents the **20% capacity student configuration**.
688
 
689
  ---
690
 
 
18
 
19
  **PolyTAO Student** is a property-conditioned Transformer model developed as part of my M.Sc. thesis, **β€œKnowledge-Distilled Transformers for Property-Conditioned Polymer Generation.”**
20
 
21
+ The project investigates whether a compressed Transformer student can retain useful generative behavior through knowledge distillation from a larger property-conditioned teacher model.
22
 
23
+ The teacher was initialized from the publicly available **`hkqiu/PolyTAO-BigSMILES_Version`** checkpoint and subsequently trained with molecular-property conditioning. The trained teacher was then frozen and used for feature-level knowledge distillation.
24
 
25
+ Multiple student configurations were investigated during the research. The checkpoint published in this repository corresponds to the **Student-20 configuration** used in the experiments.
26
 
27
+ The released checkpoint contains:
28
+
29
+ - **2 encoder layers**
30
+ - **12 decoder layers**
31
+ - **hidden dimension (`d_model`) = 768**
32
 
33
  > **Research model:** This checkpoint is provided for research and reproducibility purposes. It is not intended for production use or for making chemical or experimental decisions.
34
 
 
38
 
39
  The central research question behind PolyTAO is:
40
 
41
+ > **How does Transformer compression affect the chemical validity, property fidelity, and generative behavior of property-conditioned polymer generation models?**
42
 
43
+ Rather than evaluating only one compressed model, the research investigated multiple student configurations to study the relationship between model capacity and generative performance.
44
 
45
+ The work focuses particularly on whether internal representations learned by a larger property-conditioned teacher can be transferred to a smaller student through feature-level knowledge distillation.
46
 
47
  ---
48
 
49
  ## Model Lineage
50
 
51
+ The overall model-development pipeline is:
52
 
53
  ```text
54
  hkqiu/PolyTAO-BigSMILES_Version
55
  β”‚
56
  β–Ό
57
  Property-Conditioned Teacher
58
+ β”‚
59
  β”‚
60
  β”‚ Feature-Level
61
  β”‚ Knowledge Distillation
62
  β–Ό
63
  PolyTAO Students
64
  β”‚
 
 
 
 
 
65
  β–Ό
66
+ Capacity–Performance
67
+ Evaluation
68
  ```
69
 
70
  The publicly available `hkqiu/PolyTAO-BigSMILES_Version` checkpoint therefore serves as the starting point for the teacher model rather than being the final student model itself.
 
75
 
76
  The PolyTAO teacher is based on a **T5-style encoder-decoder Transformer architecture**.
77
 
78
+ The teacher was initialized from:
79
 
80
  ```text
81
  hkqiu/PolyTAO-BigSMILES_Version
82
  ```
83
 
84
+ using Hugging Face Transformers.
85
 
86
  The teacher architecture contains:
87
 
 
91
  d_model: 768
92
  ```
93
 
94
+ A custom property-conditioning mechanism was added to the Transformer.
95
 
96
+ The teacher receives:
97
 
98
  1. a tokenized polymer representation, and
99
  2. a 15-dimensional molecular-property vector.
100
 
101
+ The property vector is projected into the Transformer's hidden space using a learned linear projection.
102
+
103
+ Conceptually:
104
 
105
  ```text
106
  15 Molecular Properties
 
117
  β–Ό
118
  Property-Conditioned
119
  Encoder Representation
120
+ β”‚
121
+ β–Ό
122
+ Decoder
123
  ```
124
 
125
+ The property embedding is added to the encoder hidden representation before decoding.
126
 
127
+ After training, the Transformer checkpoint, tokenizer, and learned property projection are stored separately.
128
 
129
  ---
130
 
131
+ ## Published Student Architecture
132
 
133
+ The checkpoint released in this repository corresponds to the **Student-20 experimental configuration**.
134
 
135
+ The architecture stored in the released checkpoint is:
136
 
137
+ | Component | Teacher | Published Student-20 |
138
+ |---|---:|---:|
139
+ | Encoder layers | 12 | **2** |
140
+ | Decoder layers | 12 | **12** |
141
+ | Hidden dimension | 768 | **768** |
142
+ | Attention heads | 12 | **12** |
 
 
 
 
143
 
144
+ Therefore, the released checkpoint applies substantial compression to the **encoder depth**, reducing it from 12 layers to 2 layers, while retaining the 12-layer decoder configuration.
145
 
146
+ The architecture reported here is based on the actual configuration of the released checkpoint:
 
 
147
 
148
  ```text
149
+ num_layers = 2
150
+ num_decoder_layers = 12
151
+ d_model = 768
152
+ num_heads = 12
 
 
 
153
  ```
154
 
155
+ The student Transformer is initialized independently rather than directly copying the trained teacher weights.
156
+
157
+ Knowledge is transferred from the frozen teacher during training through feature-level knowledge distillation.
158
 
159
  ---
160
 
161
  ## Property Conditioning
162
 
163
+ Both teacher and student use a molecular-property conditioning mechanism.
164
 
165
+ Generation is conditioned on the following **15 molecular properties**:
166
 
167
  1. `MolWt`
168
  2. `HeavyAtomCount`
 
182
 
183
  During preprocessing, normalized versions of these properties are used when available.
184
 
185
+ The conditioning pipeline is:
186
 
187
  ```text
188
+ Property Vector
189
+ (15 dimensions)
190
+ β”‚
191
+ β–Ό
192
+ Linear Projection
193
+ β”‚
194
+ β–Ό
195
+ L2 Normalization
196
+ β”‚
197
+ β–Ό
198
+ Property Scaling
199
+ β”‚
200
+ β–Ό
201
+ Property Embedding
202
+ β”‚
203
+ β–Ό
204
+ Encoder Hidden States
205
+ β”‚
206
+ β–Ό
207
+ Conditioned Encoder
208
+ Representation
209
  ```
210
 
211
  The property embedding is scaled before being added to the encoder representation.
212
 
213
+ The training implementation uses:
214
 
215
  ```text
216
  Property scale = 0.05
217
  ```
218
 
219
+ The learned student property projection is distributed separately as:
220
+
221
+ ```text
222
+ property_proj_student.pt
223
+ ```
224
+
225
  ---
226
 
227
  ## Knowledge Distillation
228
 
229
  The student is trained using a frozen property-conditioned teacher.
230
 
231
+ For each training sample, the teacher and student receive the same tokenized polymer representation and molecular-property vector.
232
 
233
+ The teacher produces a conditioned encoder representation.
234
 
235
+ The student learns both:
236
 
237
  - the sequence-generation task, and
238
  - the internal representation produced by the teacher.
239
 
240
  ### Sequence Generation Loss
241
 
242
+ The student is trained using the standard sequence-to-sequence cross-entropy objective.
 
 
243
 
244
+ ### Feature-Level Distillation Loss
245
 
246
+ The student encoder representation is compared with the corresponding teacher encoder representation using Mean Squared Error (MSE).
247
 
248
  Conceptually:
249
 
250
  ```text
251
+ Property-Conditioned Teacher
252
+ β”‚
253
+ β–Ό
254
+ Teacher Hidden States
255
+ β”‚
256
+ β”‚
257
+ β”‚ MSE Distillation
258
+ β”‚
259
+ β–Ό
260
+ Student Hidden States
261
+ β–²
262
+ β”‚
263
+ Property-Conditioned Student
264
  ```
265
 
266
+ The implemented student training objective is:
 
 
267
 
268
  ```text
269
  Total Loss
270
  =
271
+ Cross-Entropy Loss
272
  +
273
+ Ξ± Γ— Knowledge-Distillation Loss
274
  ```
275
 
276
+ where:
277
 
278
  ```text
279
  Ξ± = 0.5
280
  ```
281
 
282
+ The teacher remains frozen during student training.
283
 
284
  ---
285
 
286
  ## Training Configuration
287
 
288
+ ### Teacher Training
289
 
290
  The teacher training configuration includes:
291
 
 
300
  | Validation ratio | `0.1` |
301
  | Precision | `32-bit` |
302
 
303
+ The teacher was trained using PyTorch Lightning.
304
 
305
+ The teacher model and tokenizer were saved using the Hugging Face `save_pretrained()` format, while the learned property projection was stored separately.
306
 
307
  ---
308
 
309
+ ### Student Training
310
 
311
  The student training configuration includes:
312
 
 
320
  | Property scale | `0.05` |
321
  | Validation ratio | `0.1` |
322
  | Random seed | `42` |
 
323
 
324
  The implementation uses:
325
 
 
327
  - PyTorch Lightning
328
  - Hugging Face Transformers
329
 
330
+ The training process monitors the sequence-generation and knowledge-distillation objectives together with validation loss.
 
 
 
 
 
331
 
332
  ---
333
 
 
335
 
336
  The research dataset was derived from the **Open Macromolecular Genome (OMG)** polymer dataset.
337
 
338
+ The experimental dataset contains approximately **99,000 polymer samples**, with each sample containing a polymer representation together with molecular-property information.
339
 
340
+ The preprocessing workflow includes:
341
 
342
  ```text
343
  Raw Polymer Data
 
358
  Model Input
359
  ```
360
 
361
+ Molecular descriptors used for conditioning and evaluation were calculated using **RDKit**.
362
 
363
+ The research dataset itself is **not distributed in this model repository**.
364
 
365
  ---
366
 
367
  ## Evaluation
368
 
369
+ Generated polymer representations are evaluated using several complementary metrics.
370
 
371
+ The evaluation considers:
372
 
373
  1. whether generated structures are chemically valid according to RDKit, and
374
+ 2. how closely the properties of valid generated structures correspond to the conditioning targets and reference distributions.
375
 
376
  ---
377
 
378
  ## Chemical Validity
379
 
380
+ Generated sequences are parsed and sanitized using RDKit.
381
 
382
+ A generated structure is counted as valid only when RDKit can successfully construct and sanitize the corresponding molecule.
383
 
384
+ For the final evaluation associated with the published **Student-20 checkpoint**:
385
 
386
  | Metric | Result |
387
  |---|---:|
 
389
  | Valid samples | 250 |
390
  | **Chemical validity** | **50.0%** |
391
 
392
+ Only chemically valid generated structures are included in downstream molecular-property evaluation.
393
 
394
  ---
395
 
 
397
 
398
  For valid generated structures, the 15 molecular properties are recalculated using RDKit.
399
 
400
+ Generated properties are then compared with the target/reference properties using several complementary metrics.
 
 
401
 
402
  ### Mean Absolute Error β€” MAE
403
 
404
+ MAE measures the average absolute difference between generated and target property values.
405
 
406
  Lower values indicate smaller average errors.
407
 
408
  ### Root Mean Squared Error β€” RMSE
409
 
410
+ RMSE measures property error while giving greater weight to larger deviations.
411
 
412
  Lower values indicate smaller errors.
413
 
414
  ### Pearson Correlation
415
 
416
+ Pearson correlation measures the linear relationship between generated and target property values.
417
 
418
  Higher positive correlation indicates stronger agreement between changes in the target property and changes in the generated property.
419
 
420
  ### Maximum Mean Discrepancy β€” MMD
421
 
422
+ MMD is used to compare generated and reference property distributions.
423
 
424
+ Lower values indicate closer distributional agreement under the selected kernel.
425
 
426
+ However, **MMD should not be interpreted in isolation**.
427
 
428
+ A low MMD value does not necessarily imply superior generative performance. A compressed model may produce simpler or less diverse structures whose aggregate property distributions nevertheless resemble the reference distribution.
429
 
430
  For this reason, MMD is interpreted jointly with:
431
 
 
439
 
440
  ## Distribution Analysis
441
 
442
+ Selected molecular-property distributions from valid generated molecules are compared with the corresponding test distributions.
443
 
444
  ### Molecular Weight
445
 
 
453
 
454
  ![Generated vs Test β€” Ring Count](RingCount_hist.png)
455
 
456
+ The generated distributions overlap substantially with the central regions of the reference distributions for these selected properties.
457
+
458
+ At the same time, the generated distributions can be narrower and may underrepresent portions of the reference tails. These plots should therefore be interpreted as a qualitative complement to the numerical metrics rather than as evidence of complete distributional equivalence.
459
 
460
  ---
461
 
462
+ ## Experimental Pipeline
463
 
464
  ```text
465
  Open Macromolecular Genome
 
476
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
477
  β”‚
478
  β–Ό
 
479
  hkqiu/PolyTAO-BigSMILES_Version
480
  β”‚
481
  β–Ό
 
485
  Teacher Hidden States
486
  β”‚
487
  β”‚
488
+ β”‚ Feature-Level
489
  β”‚ Knowledge Distillation
490
  β–Ό
491
  Property-Conditioned Student
 
500
  Valid Generated Structures
501
  β”‚
502
  β–Ό
503
+ RDKit Property Calculation
504
  β”‚
505
  β–Ό
506
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
507
+ β”‚ Chemical Validity β”‚
508
  β”‚ MAE β”‚
509
  β”‚ RMSE β”‚
510
  β”‚ MMD β”‚
511
  β”‚ Pearson Correlation β”‚
 
512
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
513
  β”‚
514
  β–Ό
 
518
 
519
  ---
520
 
521
+ ## Repository Files
522
 
523
+ The repository contains the Transformer checkpoint together with the files required for tokenization and property conditioning.
 
 
524
 
525
  ```text
526
+ PolyTAO-Student/
527
+ β”‚
528
+ β”œβ”€β”€ README.md
529
+ β”‚
530
+ β”œβ”€β”€ config.json
531
+ β”œβ”€β”€ generation_config.json
532
+ β”œβ”€β”€ model.safetensors
533
+ β”‚
534
+ β”œβ”€β”€ property_proj_student.pt
535
+ β”‚
536
+ β”œβ”€β”€ tokenizer.json
537
+ β”œβ”€β”€ tokenizer_config.json
538
+ β”œβ”€β”€ special_tokens_map.json
539
+ β”œβ”€β”€ added_tokens.json
540
+ β”‚
541
+ β”œβ”€β”€ MolWt_hist.png
542
+ β”œβ”€β”€ HeavyAtomCount_hist.png
543
+ └── RingCount_hist.png
544
  ```
545
 
546
  The standard Transformer weights are stored in:
 
549
  model.safetensors
550
  ```
551
 
552
+ The learned molecular-property projection is stored separately in:
553
 
554
  ```text
555
  property_proj_student.pt
556
  ```
557
 
558
+ This projection maps the 15-dimensional molecular-property vector into the Transformer's hidden representation.
559
 
560
+ Because property conditioning is implemented outside the standard T5 forward interface, loading only `model.safetensors` is **not sufficient to reproduce property-conditioned generation**.
561
 
562
  ---
563
 
564
+ ## Loading the Model
565
+
566
+ The Transformer checkpoint and tokenizer can be loaded directly from Hugging Face:
567
+
568
+ ```python
569
+ from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
570
+
571
+ MODEL_ID = "FahimehBahman/PolyTAO-Student"
572
+
573
+ tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
574
+
575
+ model = AutoModelForSeq2SeqLM.from_pretrained(MODEL_ID)
576
 
577
+ print("Encoder layers:", len(model.encoder.block))
578
+ print("Decoder layers:", len(model.decoder.block))
579
+ print("Hidden dimension:", model.config.d_model)
580
+ ```
581
 
582
+ For the published checkpoint, the expected architecture is:
583
 
584
+ ```text
585
+ Encoder layers: 2
586
+ Decoder layers: 12
587
+ Hidden dimension: 768
588
+ ```
589
+
590
+ ---
591
+
592
+ ## Property-Conditioned Usage
593
+
594
+ Property-conditioned inference additionally requires the learned property projection.
595
+
596
+ A simplified loading example is:
597
 
598
  ```python
599
  import torch
600
  import torch.nn as nn
601
 
602
+ from huggingface_hub import hf_hub_download
603
  from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
604
 
605
  MODEL_ID = "FahimehBahman/PolyTAO-Student"
606
 
607
+ device = torch.device(
608
+ "cuda" if torch.cuda.is_available() else "cpu"
609
+ )
610
 
611
  tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
612
 
 
620
  15,
621
  model.config.d_model
622
  ).to(device)
 
623
 
624
+ projection_path = hf_hub_download(
625
+ repo_id=MODEL_ID,
626
+ filename="property_proj_student.pt"
627
+ )
628
+
629
+ state_dict = torch.load(
630
+ projection_path,
631
+ map_location=device
632
+ )
633
 
634
+ property_proj.load_state_dict(state_dict)
635
+ property_proj.eval()
636
  ```
637
 
638
+ The complete conditioning procedure is:
 
 
639
 
640
  ```text
641
+ 15-Dimensional Property Vector
642
+ β”‚
643
+ β–Ό
644
+ Learned Projection
645
+ β”‚
646
+ β–Ό
647
+ L2 Normalization
648
+ β”‚
649
+ β–Ό
650
+ Scale by 0.05
651
+ β”‚
652
+ β–Ό
653
+ Property Embedding
654
+ β”‚
655
+ β–Ό
656
+ Encoder Hidden States
657
+ β”‚
658
+ β–Ό
 
 
 
659
  Conditioned Encoder Representation
660
+ β”‚
661
+ β–Ό
662
+ Autoregressive Decoder
663
+ β”‚
664
+ β–Ό
665
+ Generated Polymer
666
  ```
667
 
668
+ The same property normalization used during training must be applied to conditioning values before generation.
669
+
670
+ Therefore, arbitrary raw molecular-property values should **not** be passed directly to the model without reproducing the training preprocessing and normalization procedure.
671
 
672
  ---
673
 
 
677
 
678
  - knowledge distillation
679
  - Transformer model compression
680
+ - property-conditioned molecular generation
681
  - polymer generative modeling
 
682
  - efficient generative Transformer architectures
683
+ - capacity–performance analysis
684
  - evaluation of compressed generative models
685
 
686
+ The checkpoint can also serve as a research artifact for studying feature-level knowledge transfer between Transformer models.
687
 
688
  ---
689
 
 
697
  - Generated structures have not been experimentally validated.
698
  - RDKit-based validation is a computational validity check rather than experimental verification.
699
  - Property conditioning is limited to the molecular descriptors used during training.
700
+ - Correct property-conditioned inference requires reproducing the property normalization used during training.
701
  - Performance depends on preprocessing and decoding configuration.
702
+ - Property metrics are calculated only for generated structures that pass the validity checks.
703
  - Distributional similarity does not guarantee structural diversity.
704
+ - MMD should not be interpreted independently of chemical validity and other evaluation metrics.
705
+ - The released Student-20 checkpoint contains a 2-layer encoder and a 12-layer decoder; the architecture should therefore be interpreted according to the released checkpoint rather than as a uniform 20% reduction of every Transformer component.
706
+ - Results should not be used directly for safety-critical, medical, industrial, or experimental chemical decisions without independent expert validation.
707
 
708
  ---
709
 
 
713
 
714
  **Knowledge-Distilled Transformers for Property-Conditioned Polymer Generation**
715
 
716
+ The research investigates how Transformer compression and knowledge distillation affect property-conditioned polymer generation.
717
 
718
  The work combines:
719
 
 
721
  - molecular-property conditioning
722
  - feature-level knowledge distillation
723
  - model compression
724
+ - computational molecular descriptors
725
  - systematic quantitative evaluation
726
 
727
+ Multiple student configurations were investigated as part of the broader research.
728
 
729
+ The checkpoint released in this repository corresponds to the **Student-20 experimental configuration**, whose saved architecture contains **2 encoder layers and 12 decoder layers**.
730
 
731
  ---
732