README: flesh out the example and performance sections
This commit is contained in:
parent
5871292bfd
commit
accfcd2286
74
README.md
74
README.md
|
@ -14,25 +14,76 @@ as the simulation progresses or completes.
|
|||
|
||||
## Example Usage
|
||||
|
||||
simulations are defined by defining either a binary crate which links against the `coremem` library,
|
||||
simulations are defined by creating either a binary crate which links against the `coremem` library,
|
||||
or simply inserting a top-level file to the `examples/` directory in this repo and running it.
|
||||
here's the [minimal_torus](examples/minimal_torus.rs) example shipped in this library:
|
||||
here's an excerpt from the [sr_latch](examples/sr_latch.rs) example shipped in this library:
|
||||
|
||||
```rust
|
||||
# TODO: inline one of the examples/ here
|
||||
// create some `Region` instances which will define our geometry
|
||||
let ferro1_region = Torus::new_xy(Meters::new(ferro1_center, ferro_center_y, half_depth), ferro_major, ferro_minor);
|
||||
let ferro2_region = Torus::new_xy(Meters::new(ferro2_center, ferro_center_y, half_depth), ferro_major, ferro_minor);
|
||||
let set_region = Torus::new_yz(Meters::new(ferro1_center, ferro_center_y - ferro_major, half_depth), wire_major, wire_minor);
|
||||
let reset_region = Torus::new_yz(Meters::new(ferro1_center, ferro_center_y + ferro_major, half_depth), wire_major, wire_minor);
|
||||
let coupling_region = Torus::new_xz(Meters::new(0.5*(ferro1_center + ferro2_center), ferro_center_y, half_depth), wire_coupling_major, wire_minor);
|
||||
|
||||
// create the interface through which we'll "drive" a simulation to completion:
|
||||
let mut driver: SpirvDriver<spirv::FullyGenericMaterial> = Driver::new_spirv(Meters::new(width, height, depth), feat_size);
|
||||
|
||||
// fill each region within the simulation with the appropriate material
|
||||
driver.fill_region(&ferro1_region, mat::MHPgram::new(25.0, 881.33, 44000.0));
|
||||
driver.fill_region(&ferro2_region, mat::MHPgram::new(25.0, 881.33, 44000.0));
|
||||
driver.fill_region(&set_region, mat::IsomorphicConductor::new(drive_conductivity));
|
||||
driver.fill_region(&reset_region, mat::IsomorphicConductor::new(drive_conductivity));
|
||||
driver.fill_region(&coupling_region, mat::IsomorphicConductor::new(drive_conductivity));
|
||||
|
||||
// populate our stimuli.
|
||||
// here we pulse the E field with amplitude defined by a half-sine wave w.r.t. time.
|
||||
// we apply this to the "set" wire loop, everywhere directed tangential to the loop.
|
||||
let wave = Sinusoid1::from_wavelength(peak_set_field, set_pulse_duration * 2.0)
|
||||
.half_cycle()
|
||||
.shifted(start);
|
||||
driver.add_stimulus(CurlStimulus::new(
|
||||
set_region.clone(),
|
||||
wave,
|
||||
set_region.center(),
|
||||
set_region.axis()
|
||||
));
|
||||
|
||||
// every 36000 "steps", render the simulation state to disk.
|
||||
driver.add_serializer_renderer("out/examples/sr_latch/frame-", 36000, None);
|
||||
driver.step_until(Seconds(3.0*set_pulse_duration));
|
||||
```
|
||||
|
||||
you can run this with:
|
||||
you can run the full example with:
|
||||
```
|
||||
$ cargo run --example minimal_torus
|
||||
$ cargo run --release --example sr_latch
|
||||
```
|
||||
|
||||
TODO: switch between CPU and GPU accel in this demo.
|
||||
|
||||
and then investigate the results with
|
||||
```
|
||||
$ cargo run --bin viewer out/minimal_torus
|
||||
$ cargo run --bin viewer out/examples/sr_latch
|
||||
```
|
||||
![screencapture of Viewer for SR latch at t=2.8ns. it shows two rings spaced horizontally, with arrows circulating them](readme_images/sr_latch_ExBxy_2800ps.png "SR latch at t=2.8ns")
|
||||
|
||||
the viewer shows us a single xy cross-section of the simulation at a moment in time.
|
||||
it uses red-tipped arrows to show the x-y components of the B field at every point,
|
||||
and the Z component of the E field is illustrated with color (bright green for positive polarization and dark blue for negative).
|
||||
the light blue splotches depict the conductors (in the center, the wire coupling loops; on the edge, our energy-dissipating boundary).
|
||||
|
||||
what we see here is that both ferrites (the two large circles in the above image) have a clockwise polarized B field. this is in the middle of a transition, so the E fields look a bit chaotic. advance to t=46 ns: the "reset" pulse was applied at t=24ns and had 22ns to settle:
|
||||
|
||||
![screencapture of Viewer for SR latch at t=45.7ns. similar to above but with the B field polarized CCW](readme_images/sr_latch_ExBxy_45700ps.png "SR latch at t=45.7ns")
|
||||
|
||||
we can see the "reset" pulse has polarized both ferrites in the CCW orientation this time. the E field is less pronounced because we gave the system 22ns instead of 3ns to settle this time.
|
||||
|
||||
the graphical viewer is helpful for debugging geometries, but the CSV measurements are useful for viewing numeric system performance. peak inside "out/examples/sr-latch/meas.csv" to see a bunch of measurements over time. you can use a tool like Excel or [visidata](https://www.visidata.org/) to plot the interesting ones.
|
||||
|
||||
here's a plot of `M(mem2)` over time from the SR latch simulation. we're measuring the (average) M value along the major tangent to the torus corresponding to the ferrite on the right in the images above. the notable bumps correspond to these pulses: "set", "reset", "set", "reset", "set+reset applied simultaneously", "reset", "reset".
|
||||
|
||||
![plot of M(mem2) over time](readme_images/sr_latch_vd_M2.png "plot of M(mem2) over time")
|
||||
|
||||
TODO: include viewer screenshots
|
||||
|
||||
## Processing Loop
|
||||
|
||||
|
@ -73,7 +124,12 @@ TODO: document Material options, Stimulus options, Measurement options, Renderin
|
|||
|
||||
# Performance
|
||||
|
||||
TODO: document how long it takes to compute select simulations.
|
||||
|
||||
with my Radeon RX 5700XT, the sr\_latch example takes 125 minutes to complete 150ns of simulation time (3896500 simulation steps). that's on a grid of size 163x126x80 where the cell dimension is 20um.
|
||||
|
||||
in a FDTD simulation, as we shrink the cell size the time step has to shrink too (it's an inverse affine relationship). so the scale-invariant performance metric is "grid cell steps per second" (`(163*126*80)*3896500 / (125*60)`): we get 850M.
|
||||
|
||||
this is the "default" optimized version. you could introduce a new material to the simulation, and performance would remain constant. as you finalize your simulation, you can specialize it a bit and compile the GPU code to optimize for your specific material. this can squeeze another factor-of-2 gain: view <examples/buffer_proto5.rs> to see how that's done.
|
||||
|
||||
# Support
|
||||
|
||||
|
@ -84,6 +140,8 @@ this: i'm happy to spend the marginal extra time to help curious people make use
|
|||
|
||||
TODO: cite the works which were useful in getting this off the ground.
|
||||
|
||||
TODO: consult the licenses of my dependencies.
|
||||
|
||||
# License
|
||||
|
||||
i'm not a lawyer, and i don't want to be.
|
||||
|
|
Binary file not shown.
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
After Width: | Height: | Size: 44 KiB |
Loading…
Reference in New Issue