Pfc Sand Small Strain Fabric

PFC Sand Small-Strain Fabric Skill

Parent Skill Relationship

This specialist child implements pfc-workflow phases P1-P7 for sand G0:

• P1: define shape, void ratio, fabric, pressure, angle and seeds.
• P2: build clump templates and controlled orientation fabric.
• P3: install/calibrate Hertz-Mindlin contacts and consolidate.
• P4: run one declared constant-volume small-strain loop per case.
• P5: calculate G0, damping, fabric, coordination and fitted laws.
• P6/P7: verify amplitude/rate/seed/resolution independence and deliver a manifest.

When To Use

Use for G0/Gmax, small-strain sand stiffness, ellipsoidal grains, fabric anisotropy, directional modulus, cyclic-triaxial DEM, fabric tensors, mechanical coordination or G0-void-ratio relationships.

This is not a complete liquefaction model: constant volume is only a mechanical undrained analogue; explicit pore-pressure generation needs additional coupling.

Architecture Contract

All PFC code follows five layers:

Each direction case starts from the same material-ready save. Shared libraries must be idempotent: setup/reset removes prior callbacks and clears state.

Naming Contract

Namespace: ssf (sand small-strain fabric).

• FISH functions: ssf_verb_noun, e.g. ssf_compute_fabric.
• Configuration globals: ssf_cfg_*.
• Runtime state: ssf_state_*.
• Derived outputs: ssf_out_*.
• Walls: ssf_wall_xmin/xmax/ymin/ymax/zmin/zmax; never depend on wall IDs.
• Groups: ssf:grain, ssf:boundary, slot ssf_role.
• Histories: ssf/cyclic/axial_strain, ssf/cyclic/deviator_stress, etc.
• Executable command files: .p3dat; 3D FISH libraries: .p3fis; truly dimension-independent libraries only: .fis.

Case ID:

rm20_ani2_a045_e065_p100_s10001

It encodes aspect ratio, Ani level, angle, void ratio, pressure (kPa) and seed.

Save name:

ssf_{dim}_{material}_{stage}_{case_id}

Canonical stages:

ssf_3d_prep_compacted_{case_id}
ssf_3d_hertz_material_ready_{case_id}
ssf_3d_hertz_rotated_{case_id}
ssf_3d_hertz_cyclic_done_{case_id}

Physical Mapping

Core Equations

rm = la/lb
Rij = mean(n_i*n_j)
aij = (15/2)*(Rij-deltaij/3)
ad  = sqrt((3/2)*sum(aij*aij))
Zm  = (2*Nc-N1)/(Np-N1-N0)
G0  = DeltaSigma/gamma
G0  = A*exp(-a*e)*(p0/pa)^n

Use the same amplitude convention for stress and strain.

Operating Rules

1. Separate shape, density, fabric, pressure and direction in the case matrix.
2. Keep Build, Material, Test, Observe and Runner responsibilities independent.
3. Use the ssf_ namespace and named walls/groups/histories everywhere.
4. Compare G0 only at matched void ratio, pressure and approximately matched Zm.
5. Demonstrate a low-strain plateau and quasi-static energy response.
6. In constant-volume mode, use lateral DOFs only for volume control; report mean-pressure drift instead of applying a competing pressure servo.
7. Export target and achieved orientations, not only a rendered plot.
8. Write every case to output/manifest.csv with version, seed and code hash.
9. Verify target-version syntax through pfc-mcp before running.

Pipeline

Runner defines case_id
 -> Build creates templates/fabric and compacted save
 -> Material installs Hertz and creates material-ready save
 -> Observe validates ad and Zm
 -> Test restores material-ready, rotates and runs one loop
 -> Observe calculates G0/damping/energy/fabric change
 -> Runner writes cyclic-done save, log and manifest
 -> post-processing fits G0-e-p and creates orientation plots

Standard Operating Procedure

1. Read config/cases.yaml; generate one unique case ID.
2. Build sphere and 5/7/9-pebble templates for rm=1.5/2.0/2.5.
3. Check volume, centroid, inertia axes and equivalent-diameter consistency.
4. Sample Ani I/II/III orientations and compact to target void ratio.
5. Install Hertz-Mindlin and consolidate to the declared initial pressure.
6. Calculate ad and Zm; stop the case if initial-state tolerances fail.
7. Restore material-ready independently for every 0/45/90-degree case.
8. Run one complete 5 Hz loop at axial strain half-amplitude 3.0e-6.
9. Calculate G0, damping, pressure drift, volume residual and energy ratio.
10. Repeat amplitude/frequency/damping/resolution/seed checks and write manifest.

Reference Starting Values

These are reproduction starting points, not universal Toyoura-sand calibration.

Observe Interface

ssf_reset_case_state()
ssf_assert_dependencies()
ssf_sample_major_axis(ani_level)
ssf_compute_fabric()       -> ssf_out_rij/aij/ad
ssf_compute_coordination() -> ssf_out_zm
ssf_setup_measurement()
ssf_apply_cyclic_control()
ssf_should_halt()
ssf_finalize_case()

Runner Manifest

Each row records:

case_id,dim,material,shape,ani,void_ratio,pressure,angle,seed,
input_save,output_save,G0,damping,ad_before,ad_after,Zm,
volume_residual,pressure_drift,energy_ratio,status,elapsed,code_hash

Expected Trends

• G0 decreases with void ratio; the source combined fit is about R2=0.94.
• Ellipsoidal specimens are generally stiffer than spherical ones.
• For one shape/state, stronger fabric anisotropy lowers G0.
• The fabric effect increases at larger void ratio.
• At matched fabric, G0 generally increases from 0 to 45 to 90 degrees.
• Strong-fabric 90-degree cases may not obey one global exponential G0-e law.

V&V Gate

Verify clump geometry, achieved orientation, ad/Zm, particle resolution, timestep, frequency, damping, random seeds, kinetic/strain-energy ratio, volume residual and fabric change over the loop. Validate against bender-element, resonant-column or small-strain cyclic-triaxial measurements where available.

Output Contract

Deliver:

• config/cases.yaml plus config/ssf_defaults.fis;
• canonical compacted/material-ready/rotated/cyclic-done saves;
• named ssf/cyclic/* and ssf/state/* histories;
• loop data, G0, damping, void ratio, pressure drift, ad, Zm and plots;
• output/manifest.csv, logs, code hash, V&V evidence and exceptions.

Local Contents

• config/: defaults and case matrix.
• build/: template/fabric specimen creation.
• material/: Hertz-Mindlin installation/consolidation.
• test/: one declared small-strain cyclic test.
• lib/: contracts, fabric, servo and measurement interfaces.
• run/: reproducible suite runner.
• post/: G0/fabric fitting and orientation plotting.
• references/: equations, calibration cautions and expected trends.
• examples/: run order and checks.
• output/: logs, saves, histories, figures and manifest schema.