Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feat doc #15

Merged
merged 5 commits into from
Oct 25, 2023
Merged

Feat doc #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3ea6c6b
f lib doc
jtwhite79 Oct 24, 2023
93a876d
readme
jtwhite79 Oct 24, 2023
b4228e8
trying with pdoc3
jtwhite79 Oct 24, 2023
3c30ecf
trying with pdoc3
jtwhite79 Oct 24, 2023
ce0a3a5
more docs
jtwhite79 Oct 24, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,28 @@ This package is currently in pre-alpha development, and is not suitable for use,

There are several jupyter notebook examples of using pypestutils for a structured and quadtree Freyberg model. These notebooks rely on both [flopy](https://github.com/modflowpy/flopy) and [pyEMU](https://github.com/pypest/pyemu) to help with visualization and processing.

The use the low-level python interface to the shared fortran library, you create a `PESTUTILSLIB` instance and then can directly call the shared library routines:

```
from pypestutils.pestutilslib import PestUtilsLib
lib = PestUtilsLib() #the constructor searches for the shared lib
grid_info = lib.install_mf6_grid_from_file("grid","freyberg6.disv.grb")
easting,northing,elev = lib.get_cell_centres_mf6("grid",grid_info["ncells"])
```

The higher-level helper functions obsecure the calls the fortran library and string together multiple low-level function calls:

```
import pypestutils.helpers as helpers
grid_info = helpers.get_grid_info_from_file("freyberg6.disv.grb")
```

## Documentation

The documentation for pypestutils can be found [here](docs/index.html)

The documentation for the shared FORTRAN library can be found [here](docs/pestutilslib/fortran_library_documentation.md)

## Installation

### Dependencies
Expand Down
1,180 changes: 1,180 additions & 0 deletions docs/ctypes_declarations.html
View file
Open in desktop

Large diffs are not rendered by default.

758 changes: 758 additions & 0 deletions docs/data.html
View file
Open in desktop

Large diffs are not rendered by default.

584 changes: 584 additions & 0 deletions docs/enum.html
View file
Open in desktop

Large diffs are not rendered by default.

275 changes: 275 additions & 0 deletions docs/finder.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,275 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
<meta name="generator" content="pdoc 0.10.0" />
<title>pypestutils.finder API documentation</title>
<meta name="description" content="Locate pestutils shared library by any means necessary." />
<link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/11.0.1/sanitize.min.css" integrity="sha256-PK9q560IAAa6WVRRh76LtCaI8pjTJ2z11v0miyNNjrs=" crossorigin>
<link rel="preload stylesheet" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/11.0.1/typography.min.css" integrity="sha256-7l/o7C8jubJiy74VsKTidCy1yBkRtiUGbVkYBylBqUg=" crossorigin>
<link rel="stylesheet preload" as="style" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/github.min.css" crossorigin>
<style>:root{--highlight-color:#fe9}.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:30px;overflow:hidden}#sidebar > *:last-child{margin-bottom:2cm}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:1em 0 .50em 0}h3{font-size:1.4em;margin:25px 0 10px 0}h4{margin:0;font-size:105%}h1:target,h2:target,h3:target,h4:target,h5:target,h6:target{background:var(--highlight-color);padding:.2em 0}a{color:#058;text-decoration:none;transition:color .3s ease-in-out}a:hover{color:#e82}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900}pre code{background:#f8f8f8;font-size:.8em;line-height:1.4em}code{background:#f2f2f1;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{background:#f8f8f8;border:0;border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0;padding:1ex}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{margin-top:.6em;font-weight:bold}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-weight:bold;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}dt:target .name{background:var(--highlight-color)}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source summary,.git-link-div{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase}.source summary > *{white-space:nowrap;cursor:pointer}.git-link{color:inherit;margin-left:1em}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}td{padding:0 .5em}.admonition{padding:.1em .5em;margin-bottom:1em}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%;height:100vh;overflow:auto;position:sticky;top:0}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:1em}.item .name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul{padding-left:1.5em}.toc > ul > li{margin-top:.5em}}</style>
<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js" integrity="sha256-Uv3H6lx7dJmRfRvH8TH6kJD1TSK1aFcwgx+mdg3epi8=" crossorigin></script>
<script>window.addEventListener('DOMContentLoaded', () => hljs.initHighlighting())</script>
</head>
<body>
<main>
<article id="content">
<header>
<h1 class="title">Module <code>pypestutils.finder</code></h1>
</header>
<section id="section-intro">
<p>Locate pestutils shared library by any means necessary.</p>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">&#34;&#34;&#34;Locate pestutils shared library by any means necessary.&#34;&#34;&#34;
import ctypes
import os
import platform
from ctypes.util import find_library
from pathlib import Path

# the current working directory of this file
pkg_dir = Path(__file__).parent

# generate a bunch of candidate locations where the
# shared library *might* be hanging out
_candidates = [
os.environ.get(&#34;PESTUTILS_LIBRARY&#34;, None),
str(pkg_dir / &#34;lib&#34;), # see scripts/build_lib.sh
str(pkg_dir.parent / &#34;inst&#34; / (&#34;bin&#34; if os.name == &#34;nt&#34; else &#34;lib&#34;)),
&#34;.&#34;,
]


def load() -&gt; ctypes.CDLL:
&#34;&#34;&#34;Load the pestutils shared library.

Returns
-------
ctypes.CDLL
Loaded shared library
&#34;&#34;&#34;
if os.name == &#34;nt&#34;:
lib_name = &#34;pestutils.dll&#34;

# get the current PATH
oldenv = os.environ.get(&#34;PATH&#34;, &#34;&#34;).strip().rstrip(&#34;;&#34;)
# run through our list of candidate locations
for path in _candidates:
if not path or not os.path.exists(path):
continue
# temporarily add the path to the PATH environment variable
# so Windows can find additional DLL dependencies.
os.environ[&#34;PATH&#34;] = &#34;;&#34;.join([path, oldenv])
try:
rt = ctypes.cdll.LoadLibrary(os.path.join(path, lib_name))
if rt is not None:
print(&#34;lib found at&#34;,path)
return rt
except OSError:
pass
except BaseException as err:
print(f&#34;pypestutils.finder unexpected error: {err!s}&#34;)
finally:
os.environ[&#34;PATH&#34;] = oldenv
raise OSError(f&#34;could not find or load {lib_name}&#34;)

elif os.name == &#34;posix&#34;:
# posix includes both mac and linux
# use the extension for the specific platform
if platform.system() == &#34;Darwin&#34;:
# macos shared libraries are `.dylib`
lib_name = &#34;libpestutils.dylib&#34;
else:
# linux shared libraries are `.so`
lib_name = &#34;libpestutils.so&#34;

# get the starting working directory
cwd = os.getcwd()
for cand in _candidates:
if cand is None:
continue
elif os.path.isdir(cand):
# if our candidate is a directory use best guess
path = cand
target = os.path.join(cand, lib_name)
elif os.path.isfile(cand):
# if candidate is just a file use that
path = os.path.split(cand)[0]
target = cand
else:
continue

if not os.path.exists(target):
continue

try:
# move to the location we&#39;re checking
os.chdir(path)
# try loading the target file candidate
rt = ctypes.cdll.LoadLibrary(target)
if rt is not None:
print(&#34;lib found at&#34;,path)
return rt
except BaseException as err:
print(f&#34;pypestutils.finder ({target}) unexpected error: {err!s}&#34;)
finally:
os.chdir(cwd)

try:
# try loading library using LD path search
path = find_library(&#34;libpestutils&#34;)
if path is not None:
print(&#34;lib found at&#34;,path)
return ctypes.cdll.LoadLibrary(path)

except BaseException:
pass

raise OSError(&#34;Could not load pestutils library&#34;)</code></pre>
</details>
</section>
<section>
</section>
<section>
</section>
<section>
<h2 class="section-title" id="header-functions">Functions</h2>
<dl>
<dt id="pypestutils.finder.load"><code class="name flex">
<span>def <span class="ident">load</span></span>(<span>) ‑> ctypes.CDLL</span>
</code></dt>
<dd>
<div class="desc"><p>Load the pestutils shared library.</p>
<h2 id="returns">Returns</h2>
<dl>
<dt><code>ctypes.CDLL</code></dt>
<dd>Loaded shared library</dd>
</dl></div>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def load() -&gt; ctypes.CDLL:
&#34;&#34;&#34;Load the pestutils shared library.

Returns
-------
ctypes.CDLL
Loaded shared library
&#34;&#34;&#34;
if os.name == &#34;nt&#34;:
lib_name = &#34;pestutils.dll&#34;

# get the current PATH
oldenv = os.environ.get(&#34;PATH&#34;, &#34;&#34;).strip().rstrip(&#34;;&#34;)
# run through our list of candidate locations
for path in _candidates:
if not path or not os.path.exists(path):
continue
# temporarily add the path to the PATH environment variable
# so Windows can find additional DLL dependencies.
os.environ[&#34;PATH&#34;] = &#34;;&#34;.join([path, oldenv])
try:
rt = ctypes.cdll.LoadLibrary(os.path.join(path, lib_name))
if rt is not None:
print(&#34;lib found at&#34;,path)
return rt
except OSError:
pass
except BaseException as err:
print(f&#34;pypestutils.finder unexpected error: {err!s}&#34;)
finally:
os.environ[&#34;PATH&#34;] = oldenv
raise OSError(f&#34;could not find or load {lib_name}&#34;)

elif os.name == &#34;posix&#34;:
# posix includes both mac and linux
# use the extension for the specific platform
if platform.system() == &#34;Darwin&#34;:
# macos shared libraries are `.dylib`
lib_name = &#34;libpestutils.dylib&#34;
else:
# linux shared libraries are `.so`
lib_name = &#34;libpestutils.so&#34;

# get the starting working directory
cwd = os.getcwd()
for cand in _candidates:
if cand is None:
continue
elif os.path.isdir(cand):
# if our candidate is a directory use best guess
path = cand
target = os.path.join(cand, lib_name)
elif os.path.isfile(cand):
# if candidate is just a file use that
path = os.path.split(cand)[0]
target = cand
else:
continue

if not os.path.exists(target):
continue

try:
# move to the location we&#39;re checking
os.chdir(path)
# try loading the target file candidate
rt = ctypes.cdll.LoadLibrary(target)
if rt is not None:
print(&#34;lib found at&#34;,path)
return rt
except BaseException as err:
print(f&#34;pypestutils.finder ({target}) unexpected error: {err!s}&#34;)
finally:
os.chdir(cwd)

try:
# try loading library using LD path search
path = find_library(&#34;libpestutils&#34;)
if path is not None:
print(&#34;lib found at&#34;,path)
return ctypes.cdll.LoadLibrary(path)

except BaseException:
pass

raise OSError(&#34;Could not load pestutils library&#34;)</code></pre>
</details>
</dd>
</dl>
</section>
<section>
</section>
</article>
<nav id="sidebar">
<h1>Index</h1>
<div class="toc">
<ul></ul>
</div>
<ul id="index">
<li><h3>Super-module</h3>
<ul>
<li><code><a title="pypestutils" href="index.html">pypestutils</a></code></li>
</ul>
</li>
<li><h3><a href="#header-functions">Functions</a></h3>
<ul class="">
<li><code><a title="pypestutils.finder.load" href="#pypestutils.finder.load">load</a></code></li>
</ul>
</li>
</ul>
</nav>
</main>
<footer id="footer">
<p>Generated by <a href="https://pdoc3.github.io/pdoc" title="pdoc: Python API documentation generator"><cite>pdoc</cite> 0.10.0</a>.</p>
</footer>
</body>
</html>
Loading