Add example to readme docs

README.md

@@ -20,3 +20,25 @@ A package containing a library of moist thermodynamic relations
 [codecov-img]: https://codecov.io/gh/CliMA/Thermodynamics.jl/branch/main/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/CliMA/Thermodynamics.jl
 
+# Principal design
+
+This package uses an abstraction that leverages the idea of a thermodynamic state:
+
+ - given two (or more) independent intrinsic thermodynamic properties, we can establish a thermodynamic state and
+ - given a thermodynamic state, we can compute any thermodynamic property
+
+## Example
+For our example, we first load packages, and create a set of thermodynamic parameters, using a convenience constructor, offered through [CLIMAParameters.jl](https://github.com/CliMA/CLIMAParameters.jl). Then we create a thermodynamic state using density, liquid-ice potential temperature, and total specific humidity. Finally, we compute air temperature from the thermodynamic state.
+
+```julia
+import Thermodynamics as TD
+using CLIMAParameters # load convenience parameter struct wrappers
+params = TD.Parameters.ThermodynamicsParameters(Float64);
+
+ts = TD.PhaseEquil_ρθq(params, 1.0, 374.0, 0.01);
+T = TD.air_temperature(params, ts)
+```
+
+And that's it. See a full list of different thermodynamic state constructors, in case you want to create a thermodynamic state with different variables, [here](https://clima.github.io/Thermodynamics.jl/dev/API/#Thermodynamic-State-Constructors).
+
+See a full list of quantities that you can compute from a thermodynamic state, see our thermodynamic state-compatible methods [here](https://clima.github.io/Thermodynamics.jl/dev/API/#Thermodynamic-state-methods).