Reuse Builds With the Cache

Building a material runs a piecewise pwlf regression for every tabular or file-import property. That fit is the slowest part of create_material, and it produces the same result every time the source is unchanged. MaterForge caches the built result on disk so a second load of an unchanged YAML returns instantly, skipping the regression entirely.

The cache is on by default for non-plotting builds and needs no setup.

How It Works

import sympy as sp
from materforge import create_material

T = sp.Symbol('T')

# First call: builds normally and stores the result.
mat = create_material('steel.yaml', dependency=T, enable_plotting=False)

# Later call (same process or a new one): returns the cached build,
# skipping the pwlf regression.
mat = create_material('steel.yaml', dependency=T, enable_plotting=False)

A cache entry is keyed by a hash of everything that can change the result:

  • the YAML file contents,

  • the contents of every data file it references via file_path,

  • the dependency symbol name, and

  • the installed materforge and sympy versions.

Edit the YAML or any referenced data file, pass a different dependency symbol, or upgrade either library, and the key changes - so you get a fresh build automatically. There is no stale-cache trap: an entry is reused only when it provably matches.

When the Cache Is Used

The cache is consulted only when enable_plotting=False. A plotting run exists to (re)produce figures, so it always rebuilds. Opt out for a single call with use_cache=False:

create_material('steel.yaml', dependency=T, enable_plotting=False, use_cache=False)

Where It Lives, and Turning It Off

What

How

Default location

~/.cache/materforge/ (honours XDG_CACHE_HOME)

Custom location

set MATERFORGE_CACHE_DIR=/path/to/dir

Disable entirely

set MATERFORGE_DISABLE_CACHE=1

Clear it

from materforge import clear_cache; clear_cache()

The cache is always safe to delete by hand: any missing, unreadable, or version-mismatched entry is silently ignored and rebuilt.

from materforge import clear_cache

removed = clear_cache()   # returns the number of entries deleted

Next Steps