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
|
## 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.
|
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
|
```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
|
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
|
## Processing Loop
|
||||||
|
|
||||||
|
@ -73,7 +124,12 @@ TODO: document Material options, Stimulus options, Measurement options, Renderin
|
||||||
|
|
||||||
# Performance
|
# 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
|
# 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: cite the works which were useful in getting this off the ground.
|
||||||
|
|
||||||
|
TODO: consult the licenses of my dependencies.
|
||||||
|
|
||||||
# License
|
# License
|
||||||
|
|
||||||
i'm not a lawyer, and i don't want to be.
|
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