-
Notifications
You must be signed in to change notification settings - Fork 9
Expand file tree
/
Copy pathapi.html
More file actions
1623 lines (1543 loc) · 133 KB
/
Copy pathapi.html
File metadata and controls
1623 lines (1543 loc) · 133 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>API Reference — PRMS-Python v1.0.0</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="_static/custom.css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<script type="text/javascript" src="_static/copybutton.js"></script>
<script type="text/javascript" src="_static/custom.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/clipboard@1/dist/clipboard.min.js"></script>
<script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="shortcut icon" href="_static/prms-python-32x.png"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Citation" href="citation.html" />
<link rel="prev" title="Command-Line Interface" href="cli.html" />
<link href='https://fonts.googleapis.com/css?family=Ubuntu+Mono|Pacifico|Open+Sans|Metrophobic' rel='stylesheet' type='text/css'>
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo">
<a href="index.html">
<img class="logo" src="_static/prms-python-200x.png" alt="Logo"/>
</a>
</p>
<p>
<iframe src="https://ghbtns.com/github-btn.html?user=PRMS-Python&repo=PRMS-Python&type=watch&count=true&size=large&v=2"
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>
<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial and Recipes</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html#example-parameter-sensitivity">Example: Parameter sensitivity</a></li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command-Line Interface</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#classes">Classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#select-helper-functions">Select helper functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
<li class="toctree-l1"><a class="reference internal" href="citation.html">Citation</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Change log</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="cli.html" title="previous chapter">Command-Line Interface</a></li>
<li>Next: <a href="citation.html" title="next chapter">Citation</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
<h3 class="donation">Donate/support</h3>
<p>
<a class="badge" href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=JH3GLXKCGGQLG¤cy_code=USD&source=url">
<img src="https://img.shields.io/badge/donate-%E2%9D%A4%C2%A0-ff69b4.svg?style=flat" alt="Donate">
</a>
</p>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="api-reference">
<h1>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#classes" id="id15">Classes</a></p>
<ul>
<li><p><a class="reference internal" href="#data" id="id16">Data</a></p></li>
<li><p><a class="reference internal" href="#parameters" id="id17">Parameters</a></p></li>
<li><p><a class="reference internal" href="#simulation" id="id18">Simulation</a></p></li>
<li><p><a class="reference internal" href="#simulationseries" id="id19">SimulationSeries</a></p></li>
<li><p><a class="reference internal" href="#scenario" id="id20">Scenario</a></p></li>
<li><p><a class="reference internal" href="#scenarioseries" id="id21">ScenarioSeries</a></p></li>
<li><p><a class="reference internal" href="#optimizer" id="id22">Optimizer</a></p></li>
<li><p><a class="reference internal" href="#optimizationresult" id="id23">OptimizationResult</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#select-helper-functions" id="id24">Select helper functions</a></p>
<ul>
<li><p><a class="reference internal" href="#load-data" id="id25">load_data</a></p></li>
<li><p><a class="reference internal" href="#load-statvar" id="id26">load_statvar</a></p></li>
<li><p><a class="reference internal" href="#modify-params" id="id27">modify_params</a></p></li>
<li><p><a class="reference internal" href="#resample-param" id="id28">resample_param</a></p></li>
<li><p><a class="reference internal" href="#nash-sutcliffe" id="id29">nash_sutcliffe</a></p></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="classes">
<h2><a class="toc-backref" href="#id15">Classes</a><a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h2>
<div class="section" id="data">
<h3><a class="toc-backref" href="#id16">Data</a><a class="headerlink" href="#data" title="Permalink to this headline">¶</a></h3>
<span class="target" id="id1"></span><dl class="class">
<dt id="prms_python.Data">
<em class="property">class </em><code class="sig-prename descclassname">prms_python.</code><code class="sig-name descname">Data</code><span class="sig-paren">(</span><em class="sig-param">base_file=None</em>, <em class="sig-param">na_rep=-999</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/data.html#Data"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Data" title="Permalink to this definition">¶</a></dt>
<dd><p>Object to access or create a PRMS data file with ability to load/assign it to a
date-time indexed pandas.DataFrame for data management, analysis and visualization.
It can be used to build a new PRMS data file from user defined metadata and a
<code class="docutils literal notranslate"><span class="pre">pandas.DataFrame</span></code> of PRMS datetime-indexed climatic forcing and observation
variables.</p>
<p>The class properties <code class="docutils literal notranslate"><span class="pre">metadata</span></code> and <code class="docutils literal notranslate"><span class="pre">data_frame</span></code> can be later assigned if no
<code class="docutils literal notranslate"><span class="pre">base_file</span></code> is given on initialization, allowing for the creation of PRMS climatic
forcing file in a Python environment.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>base_file</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a><em>, </em><em>optional</em>) – path to standard PRMS data file</p></li>
<li><p><strong>na_rep</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.9)"><em>int</em></a><em>, </em><em>optional</em>) – how to represent missing values default = -999</p></li>
</ul>
</dd>
</dl>
<dl class="attribute">
<dt id="prms_python.Data.date_header">
<code class="sig-name descname">date_header</code><a class="headerlink" href="#prms_python.Data.date_header" title="Permalink to this definition">¶</a></dt>
<dd><p>date and time header for PRMS data file</p>
<dl class="field-list simple">
<dt class="field-odd">Type</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.9)">list</a></p>
</dd>
</dl>
</dd></dl>
<dl class="attribute">
<dt id="prms_python.Data.valid_input_variables">
<code class="sig-name descname">valid_input_variables</code><a class="headerlink" href="#prms_python.Data.valid_input_variables" title="Permalink to this definition">¶</a></dt>
<dd><p>valid hydro-climate variables for PRMS data file</p>
<dl class="field-list simple">
<dt class="field-odd">Type</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.9)">tuple</a></p>
</dd>
</dl>
</dd></dl>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If using the <code class="docutils literal notranslate"><span class="pre">Data</span></code> class to create a new data file, it is up to the user
to ensure that the metadata and <a class="reference external" href="https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html#pandas.DataFrame" title="(in pandas v1.1.4)"><code class="xref py py-class docutils literal notranslate"><span class="pre">pandas.DataFrame</span></code></a> assigned are correct
and compatible.</p>
</div>
<dl class="method">
<dt id="prms_python.Data.data_frame">
<em class="property">property </em><code class="sig-name descname">data_frame</code><a class="headerlink" href="#prms_python.Data.data_frame" title="Permalink to this definition">¶</a></dt>
<dd><p>A property that gets and sets the climatic forcing data for a standard PRMS
climate input data file as a <a class="reference external" href="https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html#pandas.DataFrame" title="(in pandas v1.1.4)"><code class="xref py py-class docutils literal notranslate"><span class="pre">pandas.DataFrame</span></code></a>.</p>
<p class="rubric">Example</p>
<p>d is a Data instance, calling</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">data_frame</span>
<span class="go"> input variables runoff 1 runoff 2 runoff 3 precip tmax tmin</span>
<span class="go"> date</span>
<span class="go"> 1996-12-27 0.54 1.6 NaN 0.0 46 32.0</span>
<span class="go"> 1996-12-28 0.65 1.6 NaN 0.0 45 24.0</span>
<span class="go"> 1996-12-29 0.80 1.6 NaN 0.0 44 28.0</span>
<span class="go"> 1996-12-30 0.90 1.6 NaN 0.0 51 33.0</span>
<span class="go"> 1996-12-31 1.00 1.7 NaN 0.0 47 32.0</span>
</pre></div>
</div>
<p>shows the date-indexed <code class="docutils literal notranslate"><span class="pre">pd.DataFrame</span></code> of the input data that is created
when a <code class="docutils literal notranslate"><span class="pre">Data</span></code> object is initiated if given a valid <code class="docutils literal notranslate"><span class="pre">base_file</span></code>, i.e.
file path to a PRMS climate data file.</p>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><ul class="simple">
<li><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#ValueError" title="(in Python v3.9)"><strong>ValueError</strong></a> – if attribute is accessed before either assigning a PRMS data
file on <code class="docutils literal notranslate"><span class="pre">Data</span></code> initialization or not assigning a compatabile
date-indexed <code class="docutils literal notranslate"><span class="pre">pandas.DataFrame</span></code> of hydro-climate variables.</p></li>
<li><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#TypeError" title="(in Python v3.9)"><strong>TypeError</strong></a> – if a data type other than <code class="docutils literal notranslate"><span class="pre">pandas.DataFrame</span></code> is assigned.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="prms_python.Data.metadata">
<em class="property">property </em><code class="sig-name descname">metadata</code><a class="headerlink" href="#prms_python.Data.metadata" title="Permalink to this definition">¶</a></dt>
<dd><p>A property that gets and sets the header information from
a standard PRMS climate input data file held in a Python dictionary. As
a property it can be assigned directly to overwrite or create a new PRMS
data file. As such the user is in control and must supply the correct
syntax for PRMS standard data files, e.g. text lines before header should
begin with “//”. Here is an example of the information gathered and held in
this attribute:</p>
<p class="rubric">Example</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data</span><span class="o">.</span><span class="n">metadata</span>
<span class="go"> {</span>
<span class="go"> 'data_startline' : 6,</span>
<span class="go"> 'data_variables' : ['runoff 1', 'runoff 2', 'tmin', 'tmax', 'ppt']</span>
<span class="go"> 'text_before_header' : "Title of data file \n //some comments\nrunoff 2</span>
<span class="go"> \ntmin 1\ntmax 1\nppt 1\nrunoff 2\ntmin 1</span>
<span class="go"> \ntmax 1\nppt 1\n</span>
<span class="go"> ########################################\n"</span>
<span class="go"> }</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>When assigning or creating a new data file, the <code class="docutils literal notranslate"><span class="pre">Data.write</span></code> method will
assign the appropriate date header that follows the line of number signs “#”.</p>
</div>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><ul class="simple">
<li><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#ValueError" title="(in Python v3.9)"><strong>ValueError</strong></a> – if data in metadata is accessed before data is assigned,
e.g. if accessed to write a PRMS data file from a <code class="docutils literal notranslate"><span class="pre">Data</span></code> instance
that was initialized without a valid PRMS data file.</p></li>
<li><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#TypeError" title="(in Python v3.9)"><strong>TypeError</strong></a> – if an object that is not a Python dictionary is assigned.</p></li>
</ul>
</dd>
<dt class="field-even">Type</dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.9)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">dict</span></code></a></p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="prms_python.Data.modify">
<code class="sig-name descname">modify</code><span class="sig-paren">(</span><em class="sig-param">func</em>, <em class="sig-param">vars_to_adjust</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/data.html#Data.modify"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Data.modify" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply a user defined function to one or more variable(s) in the data file.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">modify</span></code> method allows for inplace modification of one or more
time series inputs in the data file based on a user defined function.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>func</strong> (<em>function</em>) – function to apply to each variable in vars_to_adjust</p></li>
<li><p><strong>vars_to_adjust</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.9)"><em>list</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.9)"><em>tuple</em></a>) – collection of variable names to apply func to.</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>None</p>
</dd>
</dl>
<p class="rubric">Example</p>
<p>Here is an example of loading a data file, modifying the temperature inputs
(<em>tmin</em> and <em>tmax</em>) by adding two degrees to each element, and rewritting the
modified data to disk,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">Data</span><span class="p">(</span><span class="s1">'path_to_data_file'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
<span class="go"> return x + 2</span>
<span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">modify</span><span class="p">(</span><span class="n">f</span><span class="p">,[</span><span class="s1">'tmax'</span><span class="p">,</span><span class="s1">'tmin'</span><span class="p">])</span>
<span class="gp">>>> </span><span class="n">d</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'data_temp_plus_2'</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="prms_python.Data.write">
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">out_path</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/data.html#Data.write"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Data.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Writes the current state of the <code class="docutils literal notranslate"><span class="pre">Data</span></code> to PRMS text format
utilizing the <code class="docutils literal notranslate"><span class="pre">Data.metadata</span></code> and <code class="docutils literal notranslate"><span class="pre">Data.data_frame</span></code> instance
properties. If <code class="docutils literal notranslate"><span class="pre">Data.data_frame</span></code> was never accessed or assigned
new values then this method simply copies the original PRMS
data file to <code class="docutils literal notranslate"><span class="pre">out_path</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>out_path</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – full path to save or copy the current PRMS data
in PRMS text format.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>None</p>
</dd>
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#ValueError" title="(in Python v3.9)"><strong>ValueError</strong></a> – if the <code class="docutils literal notranslate"><span class="pre">write</span></code> method is called without assigning either
an initial data (<code class="docutils literal notranslate"><span class="pre">base_file</span></code>) path or assigning correct <code class="docutils literal notranslate"><span class="pre">metadata</span></code>
and <code class="docutils literal notranslate"><span class="pre">data_frame</span></code> properties.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="parameters">
<h3><a class="toc-backref" href="#id17">Parameters</a><a class="headerlink" href="#parameters" title="Permalink to this headline">¶</a></h3>
<span class="target" id="id2"></span><dl class="class">
<dt id="prms_python.Parameters">
<em class="property">class </em><code class="sig-prename descclassname">prms_python.</code><code class="sig-name descname">Parameters</code><span class="sig-paren">(</span><em class="sig-param">base_file</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/parameters.html#Parameters"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Parameters" title="Permalink to this definition">¶</a></dt>
<dd><p>Disk-based representation of a PRMS parameter file.</p>
<p>For the sake of memory efficiency, we only load parameters from
<code class="docutils literal notranslate"><span class="pre">base_file</span></code> that get modified through item assignment or accessed directly.
Internally, a reference is kept to only previously accessed parameter data,
so when <code class="docutils literal notranslate"><span class="pre">write</span></code> is called most copying is from <code class="docutils literal notranslate"><span class="pre">base_file</span></code> directly.
When parameters are accessed or modified using the dictionary-like syntax,
a <code class="docutils literal notranslate"><span class="pre">np.ndarray</span></code> representation of the parameter is returned. As a result
<code class="docutils literal notranslate"><span class="pre">numpy</span></code> mathematical rules including efficient vectorization of math applied
to arrays can be applied to modify parameters directly. The <code class="docutils literal notranslate"><span class="pre">Parameter</span></code>
objects user methods allow for visualization of most PRMS parameters, function
based modification of parameters, and a write function that writes the data
back to PRMS text format.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>base_file</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – path to PRMS parameters file</p>
</dd>
</dl>
<dl class="attribute">
<dt id="prms_python.Parameters.base_file">
<code class="sig-name descname">base_file</code><a class="headerlink" href="#prms_python.Parameters.base_file" title="Permalink to this definition">¶</a></dt>
<dd><p>path to PRMS parameters file</p>
<dl class="field-list simple">
<dt class="field-odd">Type</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)">str</a></p>
</dd>
</dl>
</dd></dl>
<dl class="attribute">
<dt id="prms_python.Parameters.base_file_reader">
<code class="sig-name descname">base_file_reader</code><a class="headerlink" href="#prms_python.Parameters.base_file_reader" title="Permalink to this definition">¶</a></dt>
<dd><p>file handle of PRMS parameters file</p>
<dl class="field-list simple">
<dt class="field-odd">Type</dt>
<dd class="field-odd"><p>file</p>
</dd>
</dl>
</dd></dl>
<dl class="attribute">
<dt id="prms_python.Parameters.dimensions">
<code class="sig-name descname">dimensions</code><a class="headerlink" href="#prms_python.Parameters.dimensions" title="Permalink to this definition">¶</a></dt>
<dd><p>dictionary with
parameter dimensions as defined in parameters file loaded on
initialization</p>
<dl class="field-list simple">
<dt class="field-odd">Type</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/collections.html#collections.OrderedDict" title="(in Python v3.9)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">collections.OrderedDict</span></code></a></p>
</dd>
</dl>
</dd></dl>
<dl class="attribute">
<dt id="prms_python.Parameters.base_params">
<code class="sig-name descname">base_params</code><a class="headerlink" href="#prms_python.Parameters.base_params" title="Permalink to this definition">¶</a></dt>
<dd><p>list of dictionaries of parameter
metadata loaded on initialization e.g. name, dimension(s), data
type, length of data array, and lines where data starts and ends
in file</p>
<dl class="field-list simple">
<dt class="field-odd">Type</dt>
<dd class="field-odd"><p>list of dicts</p>
</dd>
</dl>
</dd></dl>
<dl class="attribute">
<dt id="prms_python.Parameters.param_arrays">
<code class="sig-name descname">param_arrays</code><a class="headerlink" href="#prms_python.Parameters.param_arrays" title="Permalink to this definition">¶</a></dt>
<dd><p>dictionary with parameteter names as keys and
<code class="docutils literal notranslate"><span class="pre">numpy.array</span></code> and <code class="docutils literal notranslate"><span class="pre">numpy.ndarray</span></code> representations of parameter
values as keys. Initially empty, uses getter and setter functions.</p>
<dl class="field-list simple">
<dt class="field-odd">Type</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.9)">dict</a></p>
</dd>
</dl>
</dd></dl>
<p class="rubric">Example</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">Parameters</span><span class="p">(</span><span class="s1">'path/to/a/parameter/file'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">p</span><span class="p">[</span><span class="s1">'jh_coef'</span><span class="p">]</span> <span class="o">=</span> <span class="n">p</span><span class="p">[</span><span class="s1">'jh_coef'</span><span class="p">]</span><span class="o">*</span><span class="mf">1.1</span>
<span class="gp">>>> </span><span class="n">p</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'example_modified_params'</span><span class="p">)</span>
</pre></div>
</div>
<p>will read parameter information from the params file to check that
<em>jh_coef</em> is present in the parameter file, read the lines corresponding
to <em>jh_coef</em> data and assign the new value as requested. Calling
the <code class="docutils literal notranslate"><span class="pre">write</span></code> method next will copy all parameters except <em>jh_coef</em>
to the new parameter file and append the newly modified <em>jh_coef</em>
to the end of the new file from the modified values stored in the
parameter instance <code class="docutils literal notranslate"><span class="pre">p</span></code>.</p>
<dl class="method">
<dt id="prms_python.Parameters.plot">
<code class="sig-name descname">plot</code><span class="sig-paren">(</span><em class="sig-param">nrows</em>, <em class="sig-param">which='all'</em>, <em class="sig-param">out_dir=None</em>, <em class="sig-param">xlabel=None</em>, <em class="sig-param">ylabel=None</em>, <em class="sig-param">cbar_label=None</em>, <em class="sig-param">title=None</em>, <em class="sig-param">mpl_style=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/parameters.html#Parameters.plot"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Parameters.plot" title="Permalink to this definition">¶</a></dt>
<dd><p>Versatile method that plots most parameters in a standard PRMS parameter
file assuming the PRMS model was built on a uniform spatial grid.</p>
<p>Plots parameters as line plots for series or 2D spatial grid depending on
parameter dimension. The PRMS parameter file is assumed to hold parameters
for a model that was set up on a uniform rectangular grid with the spatial
index of HRUs starting in the upper left corner and moving left to
right across columns and down rows. Default function is to print four
files, each with plots of varying parameter dimensions as explained
under Kwargs <code class="docutils literal notranslate"><span class="pre">which</span></code> and more detailed explanation in the example
<a class="reference external" href="https://github.com/PRMS-Python/PRMS-Python/blob/master/notebooks/param_examples.ipynb">Jupyter notebook</a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>nrows</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.9)"><em>int</em></a>) – The number of rows in the PRMS model grid for plotting
spatial parameters. Will only work correctly for rectangular gridded models
with HRU indices starting in the upper left cell moving left to right
across columns and down across rows.</p>
</dd>
<dt class="field-even">Keyword Arguments</dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>which</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – name of PRMS parameter to plot or ‘all’. If ‘all’ then
the function will print 3 multipage pdfs, one for nhru
dimensional parameters, one for nhru by monthly parameters, one
for other parameters of length > 1, and one html file containing
single valued parameters.</p></li>
<li><p><strong>out_dir</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – path to an output dir, default current directory</p></li>
<li><p><strong>xlabel</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – x label for plot(s)</p></li>
<li><p><strong>ylabel</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – y label for plot(s)</p></li>
<li><p><strong>cbar_label</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – label for colorbar on spatial plot(s)</p></li>
<li><p><strong>title</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – plot title</p></li>
<li><p><strong>mpl_style</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a><em>, </em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.9)"><em>list</em></a>) – name or list of names of matplotlib style sheets to
use for plot(s).</p></li>
</ul>
</dd>
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p>None</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<p>If the plot method is called with the keyword argument <code class="docutils literal notranslate"><span class="pre">which</span></code> set
to a parameter that has length one, i.e. single valued it will simply
print out the value e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">Parameters</span><span class="p">(</span><span class="s1">'path/to/parameters'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">p</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">nrows</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">which</span><span class="o">=</span><span class="s1">'radj_sppt'</span><span class="p">)</span>
<span class="go"> radj_sppt is single valued with value: 0.4924942352224324</span>
</pre></div>
</div>
<p>The default action is particularly useful which makes four multi-page
pdfs of most PRMS parameters where each file contains parameters
of different dimensions e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">p</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">nrows</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">which</span><span class="o">=</span><span class="s1">'all'</span><span class="p">,</span> <span class="n">mpl_style</span><span class="o">=</span><span class="s1">'ggplot'</span><span class="p">)</span>
</pre></div>
</div>
<p>will produce the following four files named by parameters of certain
dimensions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">os</span>
<span class="gp">>>> </span><span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">getcwd</span><span class="p">())</span> <span class="c1"># list files in current directory</span>
<span class="go"> nhru_param_maps.pdf</span>
<span class="go"> nhru_by_nmonths_param_maps.pdf</span>
<span class="go"> non_spatial_param_plots.pdf</span>
<span class="go"> single_valued_params.html</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="prms_python.Parameters.write">
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">out_name</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/parameters.html#Parameters.write"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Parameters.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Writes current state of <code class="docutils literal notranslate"><span class="pre">Parameters</span></code> to disk in PRMS text format</p>
<p>To reduce memory usage the <code class="docutils literal notranslate"><span class="pre">write</span></code> method copies parameters
from the initial <code class="docutils literal notranslate"><span class="pre">base_file</span></code> parameter file for all parameters
that were never modified.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>out_name</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – path to write <code class="docutils literal notranslate"><span class="pre">Parameters</span></code> data to PRMS text
format.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>None</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="simulation">
<h3><a class="toc-backref" href="#id18">Simulation</a><a class="headerlink" href="#simulation" title="Permalink to this headline">¶</a></h3>
<span class="target" id="id3"></span><dl class="class">
<dt id="prms_python.Simulation">
<em class="property">class </em><code class="sig-prename descclassname">prms_python.</code><code class="sig-name descname">Simulation</code><span class="sig-paren">(</span><em class="sig-param">input_dir=None</em>, <em class="sig-param">simulation_dir=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/simulation.html#Simulation"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Simulation" title="Permalink to this definition">¶</a></dt>
<dd><p>Class that runs and manages file structure for a single PRMS simulation.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">Simulation</span></code> class provides low-level managment of a PRMS simulation
by copying model input files from <code class="docutils literal notranslate"><span class="pre">input_dir</span></code> argument to an output dir
<code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code>. The file stucture for an individual simulation after
calling the <code class="docutils literal notranslate"><span class="pre">run</span></code> method is simple, two subdirectories “inputs” and
“outputs” are created under <code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code> and the respective input
and output files from the current PRMS simulation are transfered there after
the <code class="docutils literal notranslate"><span class="pre">Simulation.run()</span></code> method is called which executes the PRMS model,
(see examples below in <a class="reference internal" href="#prms_python.Simulation.run" title="prms_python.Simulation.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">Simulation.run()</span></code></a>).</p>
<p>A <code class="docutils literal notranslate"><span class="pre">Simulation</span></code> instance checks that all required PRMS inputs (control,
parameters, data) exist in the expected locations. If simulation_dir is
provided and does not exist, it will be created. If it does exist it will
be overwritten.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>input_dir</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – path to directory that contains control, parameter,
and data files for the simulation</p></li>
<li><p><strong>simulation_dir</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – directory path to bundle inputs and outputs</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Example</p>
<p>see <a class="reference internal" href="#prms_python.Simulation.run" title="prms_python.Simulation.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">Simulation.run()</span></code></a></p>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#RuntimeError" title="(in Python v3.9)"><strong>RuntimeError</strong></a> – if input directory does not contain a PRMS <em>data</em>,
<em>parameters</em>, and <em>control</em> file.</p>
</dd>
</dl>
<dl class="method">
<dt id="prms_python.Simulation.from_data">
<em class="property">classmethod </em><code class="sig-name descname">from_data</code><span class="sig-paren">(</span><em class="sig-param">data</em>, <em class="sig-param">parameters</em>, <em class="sig-param">control_path</em>, <em class="sig-param">simulation_dir</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/simulation.html#Simulation.from_data"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Simulation.from_data" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a <code class="docutils literal notranslate"><span class="pre">Simulation</span></code> from a <a class="reference internal" href="#prms_python.Data" title="prms_python.Data"><code class="xref py py-class docutils literal notranslate"><span class="pre">Data</span></code></a> and <code class="xref py py-class docutils literal notranslate"><span class="pre">Parameter</span></code> object,
plus a path to the <em>control</em> file, and providing a <code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code>
where the simulation should be run.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>data</strong> (<a class="reference internal" href="#prms_python.Data" title="prms_python.Data"><code class="xref py py-class docutils literal notranslate"><span class="pre">Data</span></code></a>) – <code class="docutils literal notranslate"><span class="pre">Data</span></code> object for simulation</p></li>
<li><p><strong>parameters</strong> (<a class="reference internal" href="#prms_python.Parameters" title="prms_python.Parameters"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parameters</span></code></a>) – <code class="docutils literal notranslate"><span class="pre">Parameters</span></code> object for simulation</p></li>
<li><p><strong>control_path</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – path to control file</p></li>
<li><p><strong>simulation_dir</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – path to directory where simulations will be
run and where input and output will be stored. If it exists it will
be overwritten.</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><dl class="simple">
<dt><a class="reference internal" href="#prms_python.Simulation" title="prms_python.Simulation"><code class="xref py py-class docutils literal notranslate"><span class="pre">Simulation</span></code></a> ready to be run using <code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code> for</dt><dd><p>inputs and outputs</p>
</dd>
</dl>
</p>
</dd>
</dl>
<p class="rubric">Example</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">Data</span><span class="p">(</span><span class="s1">'path_to_data_file'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">p</span> <span class="o">=</span> <span class="n">Parameters</span><span class="p">(</span><span class="s1">'path_to_parameters_file'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="s1">'path_to_control_file'</span>
<span class="gp">>>> </span><span class="n">sim_dir</span> <span class="o">=</span> <span class="s1">'path_to_create_simulation'</span>
<span class="gp">>>> </span><span class="n">sim</span> <span class="o">=</span> <span class="n">Simulation</span><span class="o">.</span><span class="n">from_data</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="n">p</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">sim_dir</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">sim</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#TypeError" title="(in Python v3.9)"><strong>TypeError</strong></a> – if <code class="docutils literal notranslate"><span class="pre">data</span></code> and <code class="docutils literal notranslate"><span class="pre">parameters</span></code> arguments are not of type
<a class="reference internal" href="#prms_python.Data" title="prms_python.Data"><code class="xref py py-class docutils literal notranslate"><span class="pre">Data</span></code></a> and <a class="reference internal" href="#prms_python.Parameters" title="prms_python.Parameters"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parameters</span></code></a></p>
</dd>
</dl>
</dd></dl>
<dl class="method">
<dt id="prms_python.Simulation.run">
<code class="sig-name descname">run</code><span class="sig-paren">(</span><em class="sig-param">prms_exec='prms'</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/simulation.html#Simulation.run"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Simulation.run" title="Permalink to this definition">¶</a></dt>
<dd><p>Run a <code class="docutils literal notranslate"><span class="pre">Simulation</span></code> instance using PRMS input files from <code class="docutils literal notranslate"><span class="pre">input_dir</span></code>
and copy to the <code class="docutils literal notranslate"><span class="pre">Simulation</span></code> file structure under <code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code> if
given, otherwise leave PRMS input output unstructured and in <code class="docutils literal notranslate"><span class="pre">input_dir</span></code></p>
<p>This method runs a single PRMS simulation from a <code class="docutils literal notranslate"><span class="pre">Simulation</span></code> instance,
waits until the process has completed and then transfers model input and
output files to respective newly created directories. See example of the
file structure that is created under different workflows of the <code class="docutils literal notranslate"><span class="pre">run</span></code>
method below.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments</dt>
<dd class="field-odd"><p><strong>prms_exec</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – name of PRMS executable on $PATH or path to executable</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<p>If we create a <a class="reference internal" href="#prms_python.Simulation" title="prms_python.Simulation"><code class="xref py py-class docutils literal notranslate"><span class="pre">Simulation</span></code></a> instance by only assigning the
<code class="docutils literal notranslate"><span class="pre">input_dir</span></code> argument and call its <code class="docutils literal notranslate"><span class="pre">run</span></code> method the model will be
run in the <code class="docutils literal notranslate"><span class="pre">input_dir</span></code> and all model input and output files will
remain in <code class="docutils literal notranslate"><span class="pre">input_dir</span></code>,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">os</span>
<span class="gp">>>> </span><span class="n">input_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span>
<span class="go"> 'PRMS-Python',</span>
<span class="go"> 'prms_python',</span>
<span class="go"> 'models',</span>
<span class="go"> 'lbcd'</span>
<span class="go"> )</span>
<span class="gp">>>> </span><span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">input_dir</span><span class="p">)</span>
<span class="go"> ['data',</span>
<span class="go"> 'data_3deg_upshift',</span>
<span class="go"> 'parameters',</span>
<span class="go"> 'parameters_adjusted',</span>
<span class="go"> 'control']</span>
<span class="gp">>>> </span><span class="n">sim</span> <span class="o">=</span> <span class="n">Simulation</span><span class="p">(</span><span class="n">input_dir</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">sim</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">input_dir</span><span class="p">)</span> <span class="c1"># all input and outputs in input_dir</span>
<span class="go"> ['data',</span>
<span class="go"> 'data_3deg_upshift',</span>
<span class="go"> 'parameters',</span>
<span class="go"> 'parameters_adjusted',</span>
<span class="go"> 'control',</span>
<span class="go"> 'statvar.dat',</span>
<span class="go"> 'prms_ic.out',</span>
<span class="go"> 'prms.out' ]</span>
</pre></div>
</div>
<p>Instead if we assigned a path for <code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code> keyword
argument and then called <code class="docutils literal notranslate"><span class="pre">run</span></code>, i.e.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">sim</span> <span class="o">=</span> <span class="n">Simulation</span><span class="p">(</span><span class="n">input_dir</span><span class="p">,</span> <span class="s1">'path_simulation'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">sim</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>the files structure for the PRMS simulation created by <code class="docutils literal notranslate"><span class="pre">Simulation.run()</span></code>
would be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>path_simulation
├── inputs
│ ├── control
│ ├── data
│ └── parameters
└── outputs
├── data_3deg_upshift
├── parameters_adjusted
├── prms_ic.out
├── prms.out
└── statvar.dat
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>As shown in the last example, currently the <code class="docutils literal notranslate"><span class="pre">Simulation.run</span></code> routine only
recognizes the <em>data</em>, <em>parameters</em>. and <em>control</em> file as PRMS inputs,
all other files found in <code class="docutils literal notranslate"><span class="pre">input_dir</span></code> before <em>and</em> after normal completion
of the PRMS simulation will be transferred to <code class="docutils literal notranslate"><span class="pre">simulation_dir/outputs/</span></code>.</p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="simulationseries">
<h3><a class="toc-backref" href="#id19">SimulationSeries</a><a class="headerlink" href="#simulationseries" title="Permalink to this headline">¶</a></h3>
<span class="target" id="id4"></span><dl class="class">
<dt id="prms_python.SimulationSeries">
<em class="property">class </em><code class="sig-prename descclassname">prms_python.</code><code class="sig-name descname">SimulationSeries</code><span class="sig-paren">(</span><em class="sig-param">simulations</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/simulation.html#SimulationSeries"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.SimulationSeries" title="Permalink to this definition">¶</a></dt>
<dd><p>Series of simulations all to be run through a common interface.</p>
<p>Utilizes <code class="xref py py-class docutils literal notranslate"><span class="pre">multiprocessing.Pool</span></code> class to parallelize the
execution of series of PRMS simulations. SimulationSeries also
allows the user to define the PRMS executable command which is
set to “prms” as default. It is best to add the prms executable to
your $PATH environment variable. Each simulation that is run through
<code class="docutils literal notranslate"><span class="pre">SimulationSeries</span></code> will follow the strict file structure as defined
by <a class="reference internal" href="#prms_python.Simulation.run" title="prms_python.Simulation.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">Simulation.run()</span></code></a>. This class is useful particularly for
creating new programatic workflows not provided yet by PRMS-Python.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>simulations</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.9)"><em>list</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.9)"><em>tuple</em></a>) – list of <a class="reference internal" href="#prms_python.Simulation" title="prms_python.Simulation"><code class="xref py py-class docutils literal notranslate"><span class="pre">Simulation</span></code></a> objects
to be run.</p>
</dd>
</dl>
<p class="rubric">Example</p>
<p>Lets say you have already created a series of PRMS models by modifying
the input climatic forcing data, e.g. you have 100 <em>data</em> files and
you want to run each using the same <em>control</em> and <em>parameters</em> file.
For simplicity lets say there is a directory that contains all 100
<em>data</em> files e.g. data1, data2, … or whatever they are named and
nothing else. This example also assumes that you want each simulation
to be run and stored in directories named after the <em>data</em> files as
shown.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">data_dir</span> <span class="o">=</span> <span class="s1">'dir_that_contains_all_data_files'</span>
<span class="gp">>>> </span><span class="n">params</span> <span class="o">=</span> <span class="n">Parameters</span><span class="p">(</span><span class="s1">'path_to_parameter_file'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">control_path</span> <span class="o">=</span> <span class="s1">'path_to_control'</span>
<span class="gp">>>> </span><span class="c1"># a list comprehension to make multiple simulations with</span>
<span class="gp">>>> </span><span class="c1"># different data files, alternatively you could use a for loop</span>
<span class="gp">>>> </span><span class="n">sims</span> <span class="o">=</span> <span class="p">[</span>
<span class="go"> Simulation.from_data</span>
<span class="go"> (</span>
<span class="go"> Data(data_file),</span>
<span class="go"> params,</span>
<span class="go"> control_path,</span>
<span class="go"> simulation_dir='sim_{}'.format(data_file)</span>
<span class="go"> )</span>
<span class="go"> for data_file in os.listdir(data_dir)</span>
<span class="go"> ]</span>
</pre></div>
</div>
<p>Next we can use <code class="docutils literal notranslate"><span class="pre">SimulationSeries</span></code> to run all of these
simulations in parrallel. For example we may use 8 logical cores
on a common desktop computer.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">sim_series</span> <span class="o">=</span> <span class="n">SimulationSeries</span><span class="p">(</span><span class="n">sims</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">sim_series</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">nprocs</span><span class="o">=</span><span class="mi">8</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">SimulationSeries.run()</span></code> method will run all 100 simulations
where chunks of 8 at a time will be run in parrallel. Inputs and
outputs of each simulation will be sent to each simulation’s
<code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code> following the file structure of
<a class="reference internal" href="#prms_python.Simulation.run" title="prms_python.Simulation.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">Simulation.run()</span></code></a>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <a class="reference internal" href="#prms_python.Simulation" title="prms_python.Simulation"><code class="xref py py-class docutils literal notranslate"><span class="pre">Simulation</span></code></a> and <a class="reference internal" href="#prms_python.SimulationSeries" title="prms_python.SimulationSeries"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimulationSeries</span></code></a> classes
are low-level in that they alone do not create metadata for
PRMS simulation scenarios. In other words they do not produce
any additional files that may help the user know what differs
between individual simulations.</p>
</div>
<dl class="method">
<dt id="prms_python.SimulationSeries.outputs_iter">
<code class="sig-name descname">outputs_iter</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/simulation.html#SimulationSeries.outputs_iter"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.SimulationSeries.outputs_iter" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a <code class="xref py py-class docutils literal notranslate"><span class="pre">generator</span></code> of directories with the path to the
<code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code> as well as paths to the <em>statvar.dat</em> output
file, and <em>data</em> and <em>parameters</em> input files used in the simulation.</p>
<dl class="field-list">
<dt class="field-odd">Yields</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.9)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">dict</span></code></a> –</p>
<dl class="simple">
<dt>dictionary of paths to simulation directory,</dt><dd><p>input, and output files.</p>
</dd>
</dl>
</dd>
</dl>
<p class="rubric">Example</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ser</span> <span class="o">=</span> <span class="n">SimulationSeries</span><span class="p">(</span><span class="n">simulations</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">ser</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">g</span> <span class="o">=</span> <span class="n">ser</span><span class="o">.</span><span class="n">outputs_iter</span><span class="p">()</span>
</pre></div>
</div>
<p>Would return something like</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">g</span><span class="o">.</span><span class="n">next</span><span class="p">())</span>
<span class="go"> {</span>
<span class="go"> 'simulation_dir': 'path/to/sim/',</span>
<span class="go"> 'statvar': 'path/to/statvar',</span>
<span class="go"> 'data': 'path/to/data',</span>
<span class="go"> 'parameters': 'path/to/parameters'</span>
<span class="go"> }</span>
</pre></div>
</div>
</dd></dl>
<dl class="method">
<dt id="prms_python.SimulationSeries.run">
<code class="sig-name descname">run</code><span class="sig-paren">(</span><em class="sig-param">prms_exec='prms'</em>, <em class="sig-param">nproc=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/simulation.html#SimulationSeries.run"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.SimulationSeries.run" title="Permalink to this definition">¶</a></dt>
<dd><p>Method to run multiple <a class="reference internal" href="#prms_python.Simulation" title="prms_python.Simulation"><code class="xref py py-class docutils literal notranslate"><span class="pre">Simulation</span></code></a> objects in parrallel.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>prms_exec</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – name of PRMS executable on $PATH or path to
executable</p></li>
<li><p><strong>nproc</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.9)"><em>int</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.9)"><em>None</em></a>) – number of logical or physical processors
for parrallel execution of PRMS simulations.</p></li>
</ul>
</dd>
</dl>
<p class="rubric">Example</p>
<p>see <a class="reference internal" href="#prms_python.SimulationSeries" title="prms_python.SimulationSeries"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimulationSeries</span></code></a></p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If <code class="docutils literal notranslate"><span class="pre">nproc</span></code> is not assigned the deault action is to use half
of the available processecors on the machine using the Python
<a class="reference external" href="https://docs.python.org/3/library/multiprocessing.html#module-multiprocessing" title="(in Python v3.9)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">multiprocessing</span></code></a> module.</p>
</div>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="scenario">
<h3><a class="toc-backref" href="#id20">Scenario</a><a class="headerlink" href="#scenario" title="Permalink to this headline">¶</a></h3>
<span class="target" id="id5"></span><dl class="class">
<dt id="prms_python.Scenario">
<em class="property">class </em><code class="sig-prename descclassname">prms_python.</code><code class="sig-name descname">Scenario</code><span class="sig-paren">(</span><em class="sig-param">base_dir</em>, <em class="sig-param">scenario_dir</em>, <em class="sig-param">title=None</em>, <em class="sig-param">description=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/scenario.html#Scenario"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Scenario" title="Permalink to this definition">¶</a></dt>
<dd><p>Container for the process in which one modifies input parameters then
runs a simulation while tracking metadata.</p>
<p>Metadata includes a title and description, if provided, plus start/end
datetime, and parameter names of parameters that were modified including
string representations of the Python modification functions that were
applied to each parameter. The metadata file is in <a class="reference external" href="https://docs.python.org/3/library/json.html#module-json" title="(in Python v3.9)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">json</span></code></a> format
making it conveniently read as a Python dictionary.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>base_dir</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – path to directory that contains initial <em>control</em>,
<em>parameter</em>, and <em>data</em> files to be used for <code class="docutils literal notranslate"><span class="pre">Scenario</span></code>.
The <em>parameters</em> file in <code class="docutils literal notranslate"><span class="pre">base_dir</span></code> will not be modifed
instead will be copied to <code class="docutils literal notranslate"><span class="pre">scenario_dir</span></code> and them modified.</p></li>
<li><p><strong>scenario_dir</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – directory path to bundle inputs and outputs</p></li>
<li><p><strong>title</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a><em>, </em><em>optional</em>) – title of <code class="docutils literal notranslate"><span class="pre">Scenario</span></code>, if given will be
added to <code class="docutils literal notranslate"><span class="pre">Scenario.metadata</span></code> attribute as well as the
<code class="docutils literal notranslate"><span class="pre">metadata.json</span></code> file in <code class="docutils literal notranslate"><span class="pre">scenario_dir</span></code> written after
calling the <a class="reference internal" href="#prms_python.Scenario.build" title="prms_python.Scenario.build"><code class="xref py py-func docutils literal notranslate"><span class="pre">Scenario.build()</span></code></a> and <a class="reference internal" href="#prms_python.Scenario.run" title="prms_python.Scenario.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">Scenario.run()</span></code></a>
methods.</p></li>
<li><p><strong>description</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a><em>, </em><em>optional</em>) – description of <code class="docutils literal notranslate"><span class="pre">Scenario</span></code>, also
is added to <code class="docutils literal notranslate"><span class="pre">Scenario.metadata</span></code> as <code class="docutils literal notranslate"><span class="pre">title</span></code>.</p></li>
</ul>
</dd>
</dl>
<dl class="attribute">
<dt id="prms_python.Scenario.metadata">
<code class="sig-name descname">metadata</code><a class="headerlink" href="#prms_python.Scenario.metadata" title="Permalink to this definition">¶</a></dt>
<dd><p>a dictionary-like
class in <code class="xref py py-mod docutils literal notranslate"><span class="pre">prms_python.scenario</span></code> that tracks <code class="docutils literal notranslate"><span class="pre">Scenario</span></code> and
<code class="docutils literal notranslate"><span class="pre">ScenarioSeries</span></code> imformation including user-defined parameter
modifications and descriptions, and file structure.</p>
<dl class="field-list simple">
<dt class="field-odd">Type</dt>
<dd class="field-odd"><p><code class="xref py py-class docutils literal notranslate"><span class="pre">scenario.ScenarioMetadata</span></code></p>
</dd>
</dl>
</dd></dl>
<p class="rubric">Examples</p>
<p>This example is kept simple for clarity, here we adjust a
single PRMS parameter <em>tmin_lapse</em> by using a single arbitrary
mathematical function. We use the example PRMS model included
with PRMS-Python for this example,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">input_dir</span> <span class="o">=</span> <span class="s1">'PRMS-Python/test/data/models/lbcd'</span>
<span class="gp">>>> </span><span class="n">scenario_directory</span> <span class="o">=</span> <span class="s1">'scenario_testing'</span>
<span class="gp">>>> </span><span class="n">title</span> <span class="o">=</span> <span class="s1">'Scenario example'</span>
<span class="gp">>>> </span><span class="n">desc</span> <span class="o">=</span> <span class="s1">'adjust tmin_lapse using sine wave function'</span>
<span class="gp">>>> </span><span class="c1"># create Scenario instance</span>
<span class="gp">>>> </span><span class="n">scenario_obj</span> <span class="o">=</span> <span class="n">Scenario</span>
<span class="go"> (</span>
<span class="go"> base_dir=input_dir,</span>
<span class="go"> scenario_dir=scenario_directory,</span>
<span class="go"> title=title,</span>
<span class="go"> description=desc</span>
<span class="go"> )</span>
</pre></div>
</div>
<p>Next we need to build a dictionary to modify, in this case
<em>tmin_lapse</em>, here we use a vectorized sine function</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># build the modification function and dictionary</span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">a_func</span><span class="p">(</span><span class="n">arr</span><span class="p">):</span>
<span class="go"> return 4 + np.sin(np.linspace(0,2*np.pi,num=len(arr)))</span>
<span class="gp">>>> </span><span class="c1"># make dictionary with parameter names as keys and modification</span>
<span class="gp">>>> </span><span class="c1"># function as values</span>
<span class="gp">>>> </span><span class="n">param_mod_dic</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">tmin_lapse</span><span class="o">=</span><span class="n">a_func</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">scenario_obj</span><span class="o">.</span><span class="n">build</span><span class="p">(</span><span class="n">param_mod_funs</span><span class="o">=</span><span class="n">param_mod_dic</span><span class="p">)</span>
</pre></div>
</div>
<p>After building a <code class="docutils literal notranslate"><span class="pre">Scenario</span></code> instance the input files are
copied to <code class="docutils literal notranslate"><span class="pre">scenario_dir</span></code> which was assigned ‘scenario_testing’:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>scenario_testing
├── control
├── data
└── parameters
</pre></div>
</div>
<p>After calling <code class="docutils literal notranslate"><span class="pre">build</span></code> the input files from <code class="docutils literal notranslate"><span class="pre">input_dir</span></code> were
first copied to <code class="docutils literal notranslate"><span class="pre">scenario_dir</span></code> and then the functions in
<code class="docutils literal notranslate"><span class="pre">param_mod_dic</span></code> are applied the the parameters names (key)
in <code class="docutils literal notranslate"><span class="pre">param_mod_dic</span></code>. To run the <code class="docutils literal notranslate"><span class="pre">Scenario</span></code> use the the <code class="docutils literal notranslate"><span class="pre">run</span></code>
method</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">scenario_obj</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
</pre></div>
</div>
<p>Now the simulation is run and the <code class="docutils literal notranslate"><span class="pre">metadata.json</span></code> file is created,
the final file structure will be similar to this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>scenario_testing
├── inputs
│ ├── control
│ ├── data
│ └── parameters
├── metadata.json
└── outputs
├── prms_ic.out
├── prms.out
└── statvar.dat
</pre></div>
</div>
<p>Finally, here is what is contained in <code class="docutils literal notranslate"><span class="pre">metadata.json</span></code> for this example
which is also updates in the <a class="reference internal" href="#prms_python.Scenario.metadata" title="prms_python.Scenario.metadata"><code class="xref py py-attr docutils literal notranslate"><span class="pre">Scenario.metadata</span></code></a></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">scenario_obj</span><span class="o">.</span><span class="n">metadata</span>
<span class="go"> {</span>
<span class="go"> 'title': 'Scenario example',</span>
<span class="go"> 'description': 'adjust tmin_lapse using sine wave function',</span>
<span class="go"> 'start_datetime': '2018-09-01T19:20:21.723003',</span>
<span class="go"> 'end_datetime': '2018-09-01T19:20:31.117004',</span>
<span class="go"> 'mod_funs_dict': {</span>
<span class="go"> 'tmin_lapse': 'def parab(arr):</span>
<span class="go"> return 4 + np.sin(np.linspace(0,2*np.pi,num=len(arr)))'</span>
<span class="go"> }</span>
<span class="go"> }</span>
</pre></div>
</div>
<p>As shown the metadata retirieved the parameter modification function
as a string representation of the exact Python function(s) used for
modifying the user-defined parameter(s).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The main differentiator between <a class="reference internal" href="#prms_python.Scenario" title="prms_python.Scenario"><code class="xref py py-class docutils literal notranslate"><span class="pre">Scenario</span></code></a> and
<a class="reference internal" href="#prms_python.ScenarioSeries" title="prms_python.ScenarioSeries"><code class="xref py py-class docutils literal notranslate"><span class="pre">ScenarioSeries</span></code></a> is that <code class="docutils literal notranslate"><span class="pre">Scenario</span></code> is designed for modifying
one or more parameters of a <strong>single</strong> <em>parameters</em> file whereas
<code class="docutils literal notranslate"><span class="pre">ScenarioSeries</span></code> is designed for modifying and tracking the
modification of one or more parameters in <strong>multiple</strong> PRMS
<em>parameters</em> files, therefore resulting in multiple PRMS simulations.</p>
</div>
<dl class="method">
<dt id="prms_python.Scenario.build">
<code class="sig-name descname">build</code><span class="sig-paren">(</span><em class="sig-param">param_mod_funs=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/scenario.html#Scenario.build"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Scenario.build" title="Permalink to this definition">¶</a></dt>
<dd><p>Take a user-defined dictionary with param names as keys and Python
functions as values, copy the original input files as given when
initializing a <a class="reference internal" href="#prms_python.Scenario" title="prms_python.Scenario"><code class="xref py py-class docutils literal notranslate"><span class="pre">Scenario</span></code></a> instance to the <code class="docutils literal notranslate"><span class="pre">simulation_dir</span></code>
then apply the functions in the user-defined dictionary to the
parameters there. The <code class="docutils literal notranslate"><span class="pre">build</span></code> method must be called before running
the <code class="docutils literal notranslate"><span class="pre">Scenario</span></code> (calling <a class="reference internal" href="#prms_python.Scenario.run" title="prms_python.Scenario.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">Scenario.run()</span></code></a> ).</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments</dt>
<dd class="field-odd"><p><strong>param_mod_funs</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.9)"><em>dict</em></a>) – dictionary with parameter names as keys
and Python functions as values to apply to the names (key)</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>None</p>
</dd>
</dl>
<p class="rubric">Example</p>
<p>see <a class="reference internal" href="#prms_python.Scenario" title="prms_python.Scenario"><code class="xref py py-class docutils literal notranslate"><span class="pre">Scenario</span></code></a> for a full example.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">scenario_dir</span></code> that was assigned for the current
instance already exists, it will be overwritten when <code class="docutils literal notranslate"><span class="pre">build</span></code>
is invoked.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="prms_python.Scenario.run">
<code class="sig-name descname">run</code><span class="sig-paren">(</span><em class="sig-param">prms_exec='prms'</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/scenario.html#Scenario.run"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.Scenario.run" title="Permalink to this definition">¶</a></dt>
<dd><p>Run the PRMS simulation for a <em>built</em> <code class="docutils literal notranslate"><span class="pre">Scenario</span></code> instance.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments</dt>
<dd class="field-odd"><p><strong>prms_exec</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – name of PRMS executable on $PATH or path to
executable</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>None</p>
</dd>
</dl>
<p class="rubric">Examples</p>
<p>see <a class="reference internal" href="#prms_python.Scenario" title="prms_python.Scenario"><code class="xref py py-class docutils literal notranslate"><span class="pre">Scenario</span></code></a> for full example</p>
<dl class="field-list simple">
<dt class="field-odd">Raises</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#RuntimeError" title="(in Python v3.9)"><strong>RuntimeError</strong></a> – if the <a class="reference internal" href="#prms_python.Scenario.build" title="prms_python.Scenario.build"><code class="xref py py-func docutils literal notranslate"><span class="pre">Scenario.build()</span></code></a> method has not yet
been called.</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="scenarioseries">
<h3><a class="toc-backref" href="#id21">ScenarioSeries</a><a class="headerlink" href="#scenarioseries" title="Permalink to this headline">¶</a></h3>
<span class="target" id="id6"></span><dl class="class">
<dt id="prms_python.ScenarioSeries">
<em class="property">class </em><code class="sig-prename descclassname">prms_python.</code><code class="sig-name descname">ScenarioSeries</code><span class="sig-paren">(</span><em class="sig-param">base_dir</em>, <em class="sig-param">scenarios_dir</em>, <em class="sig-param">title=None</em>, <em class="sig-param">description=None</em><span class="sig-paren">)</span><a class="reference internal" href="_modules/prms_python/scenario.html#ScenarioSeries"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#prms_python.ScenarioSeries" title="Permalink to this definition">¶</a></dt>
<dd><p>Create and manage a series of model runs where parameters are modified.</p>
<p>First initialize the series with an optional title and description.
Then to build the series the user provides a list of dictionaries with
parameter-function key-value pairs, and optionally a title and
description for each dictionary defining the individual scenario.</p>
<p>The ScenarioSeries’ <code class="docutils literal notranslate"><span class="pre">build</span></code> method creates a file structure under
the series directory (<code class="docutils literal notranslate"><span class="pre">scenarios_dir</span></code>) where each subdirectory is
named with a <a class="reference external" href="https://docs.python.org/3/library/uuid.html#module-uuid" title="(in Python v3.9)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">uuid</span></code></a> which can be later matched to its title using
the metadata in <code class="docutils literal notranslate"><span class="pre">scenario_dir/series_metadata.json</span></code> (see <a class="reference external" href="https://docs.python.org/3/library/json.html#module-json" title="(in Python v3.9)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">json</span></code></a>).
In the future we may add a way for the user to access the results of
the scenario simulations directly through the <code class="docutils literal notranslate"><span class="pre">ScenarioSeries</span></code>
instance, but for now the results are written to disk. Therefore each
scenario’s title metadata can be used to refer to which parmaters were
modified and how for post-processing and analysis. One could also use
the description metadata for this purpose.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>base_dir</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – path to base inputs; ‘control’, ‘parameters’,
and ‘data’ must be present there</p></li>
<li><p><strong>scenarios_dir</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.9)"><em>str</em></a>) – directory where scenario data will be written
to; will be overwritten or created if it does not exist</p></li>
</ul>