Overview - Entrenar - Training & Optimization Library
Description: A comprehensive guide to building neural network training systems with autograd, optimizers, LoRA/QLoRA, and quantization using EXTREME TDD methodology

# Academic Research Artifacts

The research module provides tools for academic research workflows, supporting FAIR data principles, proper attribution, and reproducible science.

## Why Research Artifacts?

Academic research requires:

- Proper Attribution: CRediT taxonomy for contributor roles
- Persistent Identifiers: ORCID for authors, ROR for institutions, DOI for artifacts
- Reproducibility: Pre-registration with cryptographic commitments
- FAIR Data: RO-Crate packaging for findable, accessible, interoperable, reusable data
- Double-Blind Review: Anonymization support for peer review

## Components

### 1. Research Artifacts (ENT-019)

Core types for research metadata:

    #![allow(unused)]
    fn main() {
    use entrenar::research::{
        ResearchArtifact, Author, Affiliation, ArtifactType,
        License, ContributorRole
    };

    // Create an author with ORCID and CRediT roles
    let author = Author::new("Alice Smith")
        .with_orcid("0000-0002-1825-0097")?
        .with_affiliation(
            Affiliation::new("MIT")
                .with_ror_id("https://ror.org/03yrm5c26")?
                .with_country("US")
        )
        .with_roles([
            ContributorRole::Conceptualization,
            ContributorRole::Software,
            ContributorRole::WritingOriginal,
        ]);

    // Create a research artifact
    let artifact = ResearchArtifact::new(
        "dataset-2024-001",
        "Novel Deep Learning Dataset",
        ArtifactType::Dataset,
        License::CcBy4,
    )
    .with_author(author)
    .with_doi("10.5281/zenodo.1234567")
    .with_description("A curated dataset for ML research")
    .with_keywords(["machine learning", "computer vision"]);
    }

### 2. Citation Generation (ENT-020)

Export citations in BibTeX and CITATION.cff formats:

    #![allow(unused)]
    fn main() {
    use entrenar::research::CitationMetadata;

    let citation = CitationMetadata::new(artifact, 2024)
        .with_journal("Nature Machine Intelligence")
        .with_volume("6")
        .with_pages("123-145")
        .with_url("https://example.com/paper");

    // Generate BibTeX
    let bibtex = citation.to_bibtex();
    // @article{smith_2024_novel,
    //   author = {Smith, Alice},
    //   title = {{Novel Deep Learning Dataset}},
    //   year = {2024},
    //   ...
    // }

    // Generate CITATION.cff
    let cff = citation.to_cff();
    }

### 3. Literate Documents (ENT-021)

Parse and extract code from literate programming documents:

    #![allow(unused)]
    fn main() {
    use entrenar::research::LiterateDocument;

    let doc = LiterateDocument::parse_markdown(r#"
    Analysis

    ```python
    import numpy as np
    data = np.load("dataset.npy")
    }

Results show significant improvement. "#);

// Extract code blocks let blocks = doc.extract_code_blocks(); for block in blocks { println!("Language: {:?}", block.language); println!("Line: {}", block.line_number); println!("Code: {}", block.content); }

// Convert to HTML let html = doc.to_html();

    ### 4. Pre-Registration (ENT-022)

    Cryptographic commitment for research protocols:

    ```rust
    use entrenar::research::{PreRegistration, SignedPreRegistration, TimestampProof};
    use ed25519_dalek::SigningKey;

    // Create pre-registration
    let prereg = PreRegistration::new(
        "Effect of Treatment A on Outcome B",
        "Treatment A improves Outcome B by 20%",
        "Randomized controlled trial, n=100",
        "Two-sample t-test, alpha=0.05",
    );

    // Create cryptographic commitment
    let commitment = prereg.commit();
    println!("Commitment hash: {}", commitment.hash);

    // Sign with Ed25519
    let signing_key = SigningKey::generate(&mut rand::rngs::OsRng);
    let signed = SignedPreRegistration::sign(&prereg, &signing_key)
        .with_timestamp_proof(TimestampProof::git("abc123"));

    // Later: verify the commitment
    let reveal = prereg.reveal(&commitment)?;
    assert!(signed.verify()?);

### 5. Anonymization (ENT-023)

Double-blind review support:

    #![allow(unused)]
    fn main() {
    use entrenar::research::{AnonymizationConfig, anonymize_text};

    let config = AnonymizationConfig::new("review-salt-2024")
        .with_author_replacement("Anonymous Author")
        .with_affiliation_replacement("Anonymous Institution")
        .with_strip_doi(true);

    // Anonymize artifact
    let anon_artifact = config.anonymize(&artifact);

    // Export for double-blind review
    let json = anon_artifact.to_double_blind_json();
    // No author names, affiliations, or identifying info
    }

### 6. Jupyter Export (ENT-024)

Export to Jupyter notebook format:

    #![allow(unused)]
    fn main() {
    use entrenar::research::{NotebookExporter, KernelSpec, Cell};

    // Create notebook with Rust kernel
    let mut notebook = NotebookExporter::with_kernel(KernelSpec::evcxr());

    notebook.add_markdown("# Rust Analysis\n\nUsing entrenar for ML.");
    notebook.add_code(r#"
    use entrenar::autograd::Tensor;
    let x = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    "#);

    // Or convert from literate document
    let notebook = NotebookExporter::from_literate(&doc);

    // Export to .ipynb
    let ipynb = notebook.to_ipynb();
    std::fs::write("analysis.ipynb", ipynb)?;
    }

### 7. Citation Graph (ENT-025)

Track and aggregate citations:

    #![allow(unused)]
    fn main() {
    use entrenar::research::{CitationGraph, CitationNode, EdgeType};

    let mut graph = CitationGraph::new();

    // Add citation nodes
    graph.add_node("paper-a", CitationNode::new(citation_a, false));
    graph.add_node("paper-b", CitationNode::new(citation_b, true));
    graph.add_node("paper-c", CitationNode::new(citation_c, true));

    // Build citation relationships
    graph.add_citation("paper-a", "paper-b");
    graph.add_citation("paper-b", "paper-c");

    // Get all upstream citations (including transitive)
    let all_citations = graph.aggregate_all_citations("paper-a");

    // Export all to BibTeX
    let bibtex_all = graph.to_bibtex_all();
    }

### 8. RO-Crate Packaging (ENT-026)

Create FAIR-compliant research object packages:

    #![allow(unused)]
    fn main() {
    use entrenar::research::RoCrate;

    // Create RO-Crate from artifact
    let mut crate_pkg = RoCrate::from_artifact(&artifact, "./my-dataset");

    // Add data files
    crate_pkg.add_text_file("data/train.csv", "x,y\n1,2\n3,4");
    crate_pkg.add_text_file("README.md", "# Dataset\n\nDescription...");
    crate_pkg.add_file("model.safetensors", model_bytes);

    // Write to directory (creates ro-crate-metadata.json)
    crate_pkg.to_directory()?;

    // Or create ZIP archive
    let zip_bytes = crate_pkg.to_zip()?;
    std::fs::write("dataset.zip", zip_bytes)?;
    }

### 9. Archive Deposits (ENT-027)

Deposit to academic archives:

    #![allow(unused)]
    fn main() {
    use entrenar::research::{ArchiveDeposit, ArchiveProvider, ZenodoConfig};

    // Configure Zenodo
    let config = ZenodoConfig::new("your-api-token")
        .with_sandbox(true)  // Use sandbox for testing
        .with_community("ml-research");

    // Create deposit
    let deposit = ArchiveDeposit::new(ArchiveProvider::Zenodo, artifact)
        .with_text_file("README.md", readme_content)
        .with_file("data.zip", data_bytes);

    // Submit (returns DOI)
    let result = deposit.deposit()?;
    println!("DOI: {}", result.doi);
    println!("URL: {}", result.url);
    }

## CRediT Contributor Roles

The module supports all 14 CRediT taxonomy roles:

Role | Description
--- | ---
Conceptualization | Ideas and research goals
DataCuration | Data management and annotation
FormalAnalysis | Statistical/computational analysis
FundingAcquisition | Financial support
Investigation | Research execution
Methodology | Method development
ProjectAdministration | Project management
Resources | Materials and infrastructure
Software | Programming and development
Supervision | Oversight and leadership
Validation | Verification of results
Visualization | Data presentation
WritingOriginal | Initial draft
WritingReview | Critical review and editing

## Supported Formats

Format | Use Case
--- | ---
BibTeX | LaTeX citations
CFF | GitHub CITATION.cff
RO-Crate | FAIR data packages
Jupyter | Interactive notebooks
JSON-LD | Linked data

## Archive Providers

Provider | URL
--- | ---
Zenodo | https://zenodo.org
Figshare | https://figshare.com
Dryad | https://datadryad.org
Dataverse | https://dataverse.harvard.edu