Wish list for OpenPNM examples

[mkaguer]

@jgostick and I discussed a wishlist for OpenPNM examples. Is there anything else that should be on the list?

[xu-kai-xu]

Wish list for OpenPNM examples

Tutorial Series (N Steps to Getting Started with OpenPNM)

The following are in order

• [x] Primer on Data Types and Storage in Python

  • [x] File created
  • [x] Lists vs Numpy ndarrays
  • [x] Dicts
  • [x] Give basic demo but link out to more thorough sites
  • [x] Introduce the concept of subclassing a dict

• [ ] Network Generation and Quick Visualization

  • [x] File created
  • [x] Create various cubic lattices to get started
  • [x] Do a quick visualization
  • [x] Quickly show voronoi-delaunay to illustrate that random networks work too
  • [x] Mention imported networks (link to more detailed example)
  • [ ] Provide a link to a "Advanced Network Generation" folder

• [ ] Data Storage

  • [x] File created
  • [x] Spreadsheet analogy
  • [x] Naming conventions
  • [x] Rules for storage in the dict (maybe link to a tutorial on subclassing a dict to control the __setitem__ behavior)
  • [x] Discuss the params attribute
  • [x] Reading and writing data to dict
  • [x] Numerical data vs boolean defines properties and labels
  • [x] Introduce adjacency matrix and how we store topology as sparse adjacency matrices
  • [ ] Link to detailed tutorial in Reference Guide

• [ ] Graph Queries and Manipulation

  • [x] File created
  • [x] Introducting query methods on network objects and how to use them
  • [x] Talk about 'modes'
  • [x] Reaching into topotools to alter network
  • [ ] Overview of the topotools module and what it contains
  • [ ] Brief mention of the hidden skgraph module

• [ ] Defining Geometrical Properties with Pore-Scale Models

  • [x] File created
  • [x] Building a set of geometrical models from the library
  • [x] Choosing between spheres, cubes, etc, and their meaning
  • [x] Explain dependency handler and dependent properties
  • [ ] Editing existing models by changing arguments in the models attr
  • [x] Creating new custom models
  • [ ] Introduction to shape-factors (?)
  • [x] Pore-scale model collections
  • [ ] Creating heterogeneous domains using @ syntax

• [x] Using Labels and the @-Syntax

  • [x] File created
  • [x] Boolean masks and operations
  • [x] Creating custom labels manually and with set_label
  • [x] Using the pores and throats methods, with modes
  • [x] @ symbol shorthand
  • [x] Role in defining multiple domains

• [ ] Computing Phase Properties

  • [x] File created
  • [x] Building a Phase using known properties (e.g. constant viscosity)
  • [x] Using the built-in Species and Mixture classes
  • [x] Discuss the params attribute full of thermodynamic data
  • [x] Choosing models from the library
  • [ ] Using the chemicals and thermo packages to estimate properties
  • [x] Creating a custom phase property model (reiterated from early example)
  • [x] Using model collections via predefined classes

• [ ] Simulating Transport

  • [x] File created
  • [x] Simulate fluid flow
  • [x] Specifying conductance via pore-scale models
  • [ ] Revisit the shape-factor models (link to a detailed example of these definitions)
  • [ ] Discuss the get_conduit_data and obj['conduit.data'] feature
  • [x] Defining boundary conditions
  • [x] Computing rate
  • [x] Back-calculating network permeability

• [ ] Simulating Invasion

  • [x] File created
  • [x] Invasion percolation vs ordrinary percolation
  • [ ] Drainage vs Imbibition
  • [x] Fetching configurations at arbitrary intermediate stages

• [x] Visualization Options

  • [x] File created
  • [x] Quick plotting in Spyder
  • [x] Quick plotting in Jupyter with Plotly
  • [ ] Other options like vispy
  • [x] Full visualization with paraview (this should probably be a separate full guide, and probably a video too). Note: Paraview is now included in the same notebook.

Metrics (Actually doing something useful with openpnm)

• [x] Permeability coefficient
• [x] Effective diffusion coefficient
• [x] Porosity
• [x] Relative permeability curves
• [x] Relative diffusivity curves
• [x] Longitudinal dispersion coefficient
• [ ] Transverse dispersion coefficient
• [ ] Drainage and/or imbibition curves
• [ ] Match network to known $P_c$ curve by adjusting geometry properties

Reference Guide (The Inner Machinery)

Simulations (Detailed explanations of algorithms)

• [ ] Basic Transport

  • [x] File created
  • [ ] Topics covered
  • Define basic balance equation, and develop system of equations
  • Discuss role of 'conductance' models, link to detailed explanation
  • Applying boundary conditions
  • Adjusting settings (e.g. changing name of quantity)
  • Running and what goes on behind the scenes
  • Analyzing results (quantity and rate)

• [ ] Reactive Transport

  • [x] File created
  • [ ] Topics covered
  • Define balance equation with reactions
  • Explain the Patankar method of solving non-linear terms
  • Define source terms
  • Adjusting settings (e.g. changing relaxation factors)

• [ ] Transient Transport

  • [x] File created
  • [ ] Topics covered
  • Define transient species balance, link to example on implicit vs explicit, and high-order integrators
  • Choosing integrator
  • Adjusting settings (e.g. tolerance)

• [ ] Percolation Algorithms

  • [x] File created
  • [ ] Topics covered
  • Invasion vs Ordinary Percolation
  • Using invasion pattern in transport algorithm

• [ ] Multiphysics Transport

  • This is still in development

• [ ] Multiphase Transport

  • This is still in development

• [ ] Numerical Schemes for Solving Transient Pore Networks

  • [ ] File created
  • [ ] Topics covered
  • Define balance equations with accumulation in PNM nomenclature
  • Derive implicit vs explicit schemes
  • Discuss explicit order (i.e. RK23 vs RK45 vs CN)
  • Overview of options in scipy

• [x] Size Factors and Transport Conductance

  • [x] File created
  • [x] Topics covered
  • Clarify size vs shape factors
  • Derivations/integrals for common types
  • Combining size factor with fluid properties
  • Define 'conduits' and 'elements', and calculate conduit property
  • Compare conduit size factors with scalar size factor (i.e. from network extraction)

• [x] Explanation of Units

  • [x] File created (Note: A short notebook is created and for last section only challenge for time overhead is added.)
  • SI and absolute units
  • Gotchas when using gauge pressure
  • Challenges with using a unit package (i.e. pore scale models may break, views drop units)

Software Architecture

• [ ] Projects and the Workspace

  • [x] File created
  • [x] Topics covered
  • Not needed for front end use but both play a major role behind the scenes for 'object' lookup
  • Also useful for saving and loading

• [ ] Import/export Formats

  • [ ] File created
  • [ ] Topics covered
  • Define the the OpenPNM spreadsheet format in detail
  • Describe the other IO options and why we read many but write few

• [ ] Base Class Inheritance

  • [ ] File created
  • [ ] Topics covered
  • Describe the main features of Base2
  • Describe the mixins (Models)
  • Settings and their inheritance

• [ ] Algorithm Inheritance

  • [ ] File created
  • [ ] Topics covered
  • Generic -> Transport -> Reactive -> Transient
  • Generic -> Percolation

• [ ] Dependency Handler

  • [ ] File Created
  • Topic covered
  • [ ] Identifying dependencies via propnames
  • [ ] NetworkX graph resolution
  • [ ] etc

Network Representation, Generation, and Manipulation

• [ ] Storing Topology and Graph Queries

  • [ ] File created
  • [ ] Topics covered
  • Mention incidence matrices
  • Sparse representations of AM and IM
  • Different forms of the AM and IM are used for different tasks

• [ ] Explanation of skgraph module

  • [ ] File created
  • definition of directed and non-directed
  • other conventions (tbd)

• [ ] Advanced Network Generation

  • [ ] File created
  • [ ] Topics covered
  • Details of all network generation classes

• [ ] Manipulating Networks

  • [ ] File created
  • [ ] Topics covered
  • Adding and removes pores and throats
  • What happens when network is changed
  • Handle addition of locations (nans and bools)
  • Merging and joining strategies

[xu-kai-xu]

@mkaguer, hi, I just made the wish list easier to recognize. But there is one word I don't know. Simulations: develope or pro user [this place].

Also, I tried to add a new conductance calculation model for shale oil. But then the version has changed and I have to re-code some snippets. So, can you add an example about how to set a user-defined conductance? Thanks!

[jgostick]

Hi @xu-kai-xu, thanks for transcribing this list! Hopefully you can tell that we're trying to finalize V3, so are starting to think about how to best explain the new code, which is mostly familiar but has lots of excess stuff cut out and several changes to make life easier for users.