FeCIM Lattice Tools

Simulation-first desktop lab for ferroelectric compute-in-memory (FeCIM) systems.

FeCIM Lattice Tools combines a Go/Fyne desktop simulator, literature-aware validation workspace, EDA/export utilities, and a static Astro project site. It is built for learning and inspecting how ferroelectric device assumptions propagate through crossbar arrays, peripheral circuits, inference examples, and design artifacts.

Quick Start

git clone https://github.com/TrebuchetDynamics/fecim-lattice-tools.git
cd fecim-lattice-tools
go run ./cmd/fecim-lattice-tools

Run checks:

go test ./...
make test-legacy-fyne
bash scripts/reproduce_validation.sh

What This Repository Is

Use it for	Do not treat it as
Learning hysteresis, crossbar non-idealities, CIM tradeoffs, and EDA export flows.	A silicon measurement report, foundry PDK, product benchmark, or device performance claim.
Comparing simulation assumptions across materials, arrays, circuits, and algorithms.	Proof that a specific device achieves a stated accuracy, energy, endurance, or analog state count.
Building literature-backed validation checks and reproducible educational examples.	A source of uncited scientific facts.

Core physics references include Materlik 2015, Park 2015, Alessandri 2018, and Guo 2018. Parameters are either cited, range-checked, or explicitly labeled as educational defaults.

At a Glance

Question	Answer
What is it?	A Go Fyne desktop app, validation workspace, EDA/export toolkit, and Astro landing page for FeCIM simulation.
Who is it for?	Students, instructors, researchers, device/circuit/architecture designers, and open-source contributors.
What can I run?	Seven GUI modules, headless validation scripts, module tests, EDA/export examples, and the static web landing page.
What is the boundary?	Simulation and education only unless a claim is cited and covered by validation.

Table of Contents

• Quick Start
• What This Repository Is
• At a Glance
• What You Can Do
• Scope and Claim Boundary
• Modules
• Getting Started
• Main Commands
• Web Landing Page
• Configuration
• Technical Architecture
• Development Standard
• Validation
• Trust Boundaries
• Citation System
• Repository Layout
• Documentation
• Contributing and Support
• License

What You Can Do

FeCIM Lattice Tools keeps device, array, circuit, algorithm, and export assumptions in one inspectable tool. Use it to:

• Visualize P-E loops, coercive-field behavior, remanent polarization, and minor loops.
• Compare Preisach and Landau-Khalatnikov hysteresis behavior under different material presets.
• Study how conductance quantization, IR drop, sneak paths, and drift affect crossbar MVM.
• Run example inference experiments to see how CIM constraints change algorithm behavior.
• Explore peripheral read/program paths, DAC/ADC/TIA abstractions, and ISPP write control.
• Generate EDA-oriented artifacts for SPICE, Verilog, Liberty, DEF, and LEF-style flows.
• Reproduce internal validation checks and extend them with literature-backed tests.

Scope and Claim Boundary

This repository follows an accuracy-first documentation policy:

• External scientific claims must be cited and listed in the honesty audit.
• Simulation defaults must be described as defaults, placeholders, assumptions, or range-checked parameters.
• Unverified conference, marketing, or talk claims must not be presented as technical facts.
• Testable behavior should be covered by automated tests before implementation changes are accepted.
• Source-backed facts should be recorded in the Markdown-native citation system.

For current verified claims, known gaps, and removed or restricted claims, read Scientific Honesty Audit.

Modules

Module	Directory	Purpose
1	module1-hysteresis/	P-E curves, Preisach modeling, LK dynamics, material presets, and ISPP write behavior.
2	module2-crossbar/	Crossbar MVM, conductance levels, IR drop, sneak paths, drift, and array effects.
3	module3-mnist/	Example inference pipeline for studying algorithm behavior under CIM constraints.
4	module4-circuits/	Peripheral circuit abstractions for DAC, ADC, TIA, read paths, and program paths.
5	module5-comparison/	Comparison views for assumptions, metrics, and operating conditions.
6	module6-eda/	EDA export and integration utilities for design-oriented workflows.
7	module7-docs/	Integrated documentation, references, and educational material.

Shared infrastructure lives in shared/, and validation suites live in validation/.

Getting Started

Prerequisites

• Go 1.25 or newer.
• A desktop environment for the Fyne GUI.
• CGO-capable Go toolchain/system graphics libraries for Fyne.
• Node.js/npm only when developing, validating, or deploying the Astro web landing page.

Install and Run

The default desktop app is the restored Fyne shell:

git clone https://github.com/TrebuchetDynamics/fecim-lattice-tools.git
cd fecim-lattice-tools
go run ./cmd/fecim-lattice-tools

Build

go build -o fecim-lattice-tools ./cmd/fecim-lattice-tools
./fecim-lattice-tools

Verify

go test ./...
make test-legacy-fyne
bash scripts/reproduce_validation.sh

Main Commands

Open a specific GUI module:

go run ./cmd/fecim-lattice-tools --module hysteresis
go run ./cmd/fecim-lattice-tools --module crossbar
go run ./cmd/fecim-lattice-tools --module eda

Inspect available materials and launcher flags:

go run ./cmd/fecim-lattice-tools --list-materials
go run ./cmd/fecim-lattice-tools --help

Generate fresh README-style screenshots:

go run ./cmd/fecim-screenshotter-fyne -out docs/assets -only hysteresis -tag readme -w 1280 -h 820

The Fyne screenshotter follows the restored desktop path.

See CLI Reference for the full launcher and module command reference.

Web Landing Page

The web/ folder is a static Astro site for the public project landing page. It is separate from the native Go/Fyne simulator. The old Go WASM/Fyne browser demo was retired; web/ no longer loads fecim.wasm, wasm_exec.js, or cmd/fecim-web-fyne.

Develop locally:

cd web
npm install
npm run dev

Validate and build:

cd web
npm test
npm run build
npm run test:e2e   # optional browser layout gate when Chromium is available

Deploy with Cloudflare Wrangler:

cd web
npm run deploy

web/wrangler.toml targets the Cloudflare Pages project fecim and publishes web/dist. Deployment requires Wrangler authentication, for example wrangler login or a CLOUDFLARE_API_TOKEN environment variable. Add native-app screenshots under web/public/screenshots/ when they are ready.

Configuration

No API keys or cloud credentials are required for the default app, tests, or validation workflows. Cloudflare credentials are needed only for cd web && npm run deploy.

Simulation settings live in YAML files under config/:

File	Purpose
config/materials.yaml	Material presets and ferroelectric parameters.
config/constants.yaml	Shared physical constants and default level assumptions.
config/simulation.yaml	Simulation time-step and solver defaults.
config/crossbar.yaml	Crossbar geometry and array assumptions.
config/mnist.yaml	Example inference experiment settings.
config/energy.yaml	Educational energy model inputs.

For the full schema and loading behavior, read Configuration Reference. Config values that are not externally validated must stay labeled as defaults or assumptions.

Technical Architecture

Tech stack:

• Language: Go 1.25+
• Desktop UI: Fyne is the default desktop shell.
• Web: Astro static landing page in web/, deployed from web/dist through Cloudflare Pages.
• Validation: Go tests, golden data, literature range checks, and reproducibility scripts
• Exports: SPICE, Verilog, Liberty, DEF, and LEF-oriented outputs

High-level flow:

cmd/fecim-lattice-tools       default Fyne desktop shell
        |
        v
shared/ viewmodel, physics, logging, rendering, utilities
        |
        +--> module1-hysteresis  --> ferroelectric model behavior
        +--> module2-crossbar    --> array MVM and non-idealities
        +--> module3-mnist       --> example inference experiment
        +--> module4-circuits    --> read/program path abstractions
        +--> module5-comparison  --> assumption and metric comparison
        +--> module6-eda         --> design/export artifacts
        +--> module7-docs        --> integrated documentation
        |
        v
validation/ regression, literature, and integration checks

Development Standard

This project uses test-driven development for code changes:

• Write or update a failing test before changing behavior.
• Keep tests tied to observable physics, CLI, GUI, export, or validation behavior.
• Label simulation assumptions clearly in code and docs.
• Run formatting and tests before pushing.

Common checks:

gofmt -w .
go test ./...
make test-legacy-fyne
go test -race -short ./shared/... ./validation/...

See Contributing and Testing Guide for the full workflow.

Validation

The validation layer checks internal model behavior and selected literature-backed ranges. Current validation includes:

• Physics regression tests and golden data.
• Literature range checks for selected HZO and ferroelectric parameters.
• Kirchhoff-law checks for crossbar current behavior.
• Integration tests for module-level behavior.
• CI enforcement on main.

Validation does not turn educational defaults into measured device claims. If a parameter is not validated against a specific paper or dataset, it must remain labeled as an assumption or default.

Trust Boundaries

Use docs/TRUST.md to decide which outputs are highly validated, literature-backed, educational, planned, or not validated. Use docs/HOW_TO_BREAK_THIS.md and docs/PREDICTIONS.md to review adversarial stress cases and pre-registered validation targets.

Citation System

Citations live in plain Markdown under citations/. Each source gets a reviewable paper record, verified facts are promoted into citations/facts.md, and unresolved conflicts are tracked in citations/disputed.md.

Use the citation system before adding external scientific claims to code, documentation, validation reports, or the paper draft.

Repository Layout

fecim-lattice-tools/
├── cmd/                    # GUI and utility entrypoints
├── citations/              # Markdown-native source records and facts database
├── module1-hysteresis/     # Ferroelectric hysteresis and switching models
├── module2-crossbar/       # Crossbar simulation and non-idealities
├── module3-mnist/          # Example inference pipeline
├── module4-circuits/       # Peripheral circuit abstractions
├── module5-comparison/     # Technology and assumption comparison
├── module6-eda/            # EDA export utilities
├── module7-docs/           # Integrated documentation viewer
├── shared/                 # Common physics, UI, logging, and utility code
├── web/                    # Astro landing page and Cloudflare Pages config
├── docs/                   # User, developer, research, paper, notebook, and presentation docs
├── data/                   # Simulation inputs and lookup data
├── tools/                  # Developer/research tooling, prompts, and validation protocols
└── validation/             # Regression, literature, and integration checks

Documentation

• Installation
• Technical Architecture
• Configuration Reference
• Testing Guide
• Web Landing Page
• Trust Boundaries
• Citation System
• Scientific Honesty Audit
• Contributing
• Changelog

Module READMEs:

• Module 1 - Hysteresis
• Module 2 - Crossbar
• Module 3 - MNIST
• Module 4 - Circuits
• Module 5 - Comparison
• Module 6 - EDA
• Module 7 - Docs

Contributing and Support

Use GitHub issues for bugs, research gaps, documentation problems, and feature proposals:

• Repository: TrebuchetDynamics/fecim-lattice-tools
• Contribution guide: CONTRIBUTING.md
• Pull request checklist: .github/pull_request_template.md

Useful roadmap directions are tracked through issues and PRs. High-value contributions include stronger validation coverage, clearer educational examples, improved screenshots and demos, better EDA export examples, and documentation that labels assumptions precisely.

License

This project is licensed under the MIT License. See LICENSE.