austaltools

austaltools

usage: austaltools [-h] [--version] [--debug | -v] [-d PATH] [--temp-dir PATH]
                   COMMAND ...

Positional Arguments

COMMAND

Possible choices: import-buildings, bg, eap, fill-timeseries, ft, heating, plot, simple, steepness, terrain, transform, weather, volout, windfield, windrose

sub-commands help

Named Arguments

--version

show program’s version number and exit

--debug

show informative output

-v, --verbose

show detailed output

-d, --working-dir

woking directory [.]

Default: '.'

--temp-dir

directory where temporary filesare stored. None means use systemtemporary files dir. [None]

Sub-commands

import-buildings (bg)

get buildings from geojson and write to austal.txt

austaltools import-buildings [-h] [-g FILE] [-n] [-t TOLERANCE] [-z ZVALUE |
                             -Z HEIGHT] [-b] [-l] [-c COLORMAP]
                             [-k {contour,grid}] [-p [FILE]] [-f]

Named Arguments

-g, --geojson

file containing building info[haeuser.geojson]

Default: 'haeuser.geojson'

-n, --dry-run

do not change austal.txt, show changes instead.

Default: False

-t, --tolerance

limit for accepting a polygon as rectangle (max difference of the lenght of the diagonals) [0.50]

Default: 0.5

-z, --zvalue

name of property that gives building height[height]

Default: 'height'

-Z, --height

height of all buildings

-b, --no-buildings

do not show the buildings defined in config file

Default: True

-l, --low-colors

use only few discrete colors for better print results

Default: False

-c, --colormap

name of colormap to use. Defaults to “YlOrRd”

Default: 'YlOrRd'

-k, --kind

Possible choices: contour, grid

choose kind of display. contour produces filled contours, grid produces coloured grid cells. Defaults to contour

Default: 'contour'

-p, --plot

save plot to a file. If FILE is “-” the plot is shown on screen. If FILE is missing, the file name defaults to the data file name with extension png

-f, --force

force overwriting plotfile if it exists.

Default: False

eap

find substitute anemometer position according to VDI 3783 Part 16 from a wind library generated by AUSTAL

austaltools eap [-h] [-a] [-g [ID]] [-o] [-q]
                [-r {general,simple,file,austal}] [-z [METERS]]
                [--edge-nodes [EDGE_NODES]] [--max-height [MAX_HEIGHT]]
                [--min-ff [MIN_FF]] [--vdi-reference] [-b] [-l] [-c COLORMAP]
                [-k {contour,grid}] [-p [FILE]] [-f]

Named Arguments

-a, --austal

write EAP as anemometer position intoAUSTAL config file austal.txt

Default: False

-g, --grid

ID (number) of the grid to evaluate. Defaults to 0

Default: 0

-o, --overwrite

force overwriting wind reference file if it exists.

-q, --report

show detailed results

Default: False

-r, --reference

Possible choices: general, simple, file, austal

choose kind of reference profile. general produces vdi 3783-8 reference wind profiles based on vdi 3783-16 geostrophic wind values, simple produces vdi 3783-8 reference wind profiles based on measured wind speed values (needs a timeseries “az” configured in austal.txt), austal runs AUSTAL to create a wind library from which it extracts the reference wind profiles, file reads reference profile from file Ref1d.dat. Defaults to standard

Default: 'simple'

-z, --height

effective anemometer height, i.e. height to evaluate EAP at in m. Defaults to 10.0

-b, --no-buildings

do not show the buildings defined in config file

Default: True

-l, --low-colors

use only few discrete colors for better print results

Default: False

-c, --colormap

name of colormap to use. Defaults to “YlOrRd”

Default: 'YlOrRd'

-k, --kind

Possible choices: contour, grid

choose kind of display. contour produces filled contours, grid produces coloured grid cells. Defaults to contour

Default: 'contour'

-p, --plot

save plot to a file. If FILE is “-” the plot is shown on screen. If FILE is missing, the file name defaults to the data file name with extension png

-f, --force

force overwriting plotfile if it exists.

Default: False

advanced options

--edge-nodes

number of edge nodes along each side, where data are exluded. Defaults to 3

Default: 3

--max-height

maximum height to evaluate EAP. Defaults to 100.000000

Default: 100.0

--min-ff

minimum wind speed below which data are exluded. Defaults to 0.500000

Default: 0.5

--vdi-reference

Use linear wind profile interpolation for comparison with VDI 3783 p 16 reference implementation.

Default: False

fill-timeseries (ft)

fill source-strength columns in “zeitreihe.dmna”

Detailed userguide see: austaltools fill-timeseries

austaltools fill-timeseries [-h] (-l | -c | -w | -W) [-b HOUR] [-e HOUR]
                            [-u HOLIDAY_WEEK [HOLIDAY_WEEK ...] |
                            -U HOLIDAY_MONTH [HOLIDAY_MONTH ...]]
                            [-f CYCLE_FILE] [-s COLUMN_ID] [-o OUTPUT]

Named Arguments

-l, --list

list column column IDs in fileand exit without modifying “zeitreihe.dmna”. [default]

-c, --cycle

use production cycle from file

-w, --week-5

source active Mon-Fri

-W, --week-6

source active Mon-Sat

-b, --hour-begin

daily work begin time in hours 0-23. Only relevant with -w or -W. [08]

Default: 8

-e, --hour-end

daily work end time in hours, 0-23. Only relevant with -w or -W .[17]

Default: 17

-u, --holiday-week

work-free weeks 1-52 as space-delimited list. Only relevant with -w or -W. [25 26 27 28 29 30 52]

Default: [25, 26, 27, 28, 29, 30, 52]

-U, --holiday-month

work-free months as space-delimited list(1-12). Only relevant with -w or -W. 7]

Default: [7]

-f, --cycle-file

emission-cycle description file. only relevant with -c. [cycle.yaml]

Default: 'cycle.yaml'

-s, --column-id

column ID. Required if more than one column. list IDs in file with -l.

-o, --output

output for the column in g/s. -o is relevant with -w or -W.

heating

simulate a building with heating.

For a description fo the heating description file `` see: austaltools heating

austaltools heating [-h] [-f FILE] [-b BUILDING] [-x EXTRACTED_WEATHER]
                    [-o FILE] [--flush FLUSH] [--radiation RADIATION]
                    [--recording FREQ] [--record-slabs SLABOUT]
                    [--slabs SLABS] [--spreadsheet-export FILE |
                    --spreadsheet-import FILE] [--timestep TIMESTEP]

Named Arguments

-f, --heating-file

building/heating description file. [heating.yaml]

Default: 'heating.yaml'

-b, --building

name of the building to simulate. [default]

Default: 'default'

-x, --extracted-weather

name of the file containing the weather data [extracted_weather.csv].

Default: 'extracted_weather.csv'

-o, --output

name for the output file. [heating.csv]

Default: 'heating.csv'

advanced options

--flush

enable or disable continuous writingof recorded data, applys only if --recording is enabled [True].

Default: True

--radiation

enable or disable radiative heat gainon outside walls [True].

Default: True

--recording

recording interval for internal modelvariables or None for no recording. Must be a valid pandas frequency string (see Pandas documentation), for example 1min. [None]

--record-slabs

record internal model variables for each individual wall slab[False]

Default: False

--slabs

change the default value how walls are partitioned into slabs [even]. Possible selections are:

  • even: envenly spaced slabs, if the wall thickness is not a multiple of the slab size, the remainder is added to the slab in the middle

  • exponential: slab size exponentially increases from the minimal width of 0.01m at the surfaces to the center. All slabs are muliples of 0.005m.

  • a number: like even but this thickness in m is applied to all slabs, instead of the default value of 0.04 m

Default: 'even'

--spreadsheet-export

export rooms and walls from the yaml file specified by -f/–heating-file to a spreadsheet. The file format of the spreadsheet is inferred from the filename extension (.ods, .xls, or .xslx).The building name is default or must be given by -b/–building. The program exits after exporting the spreadsheet data.

--spreadsheet-import

import rooms and walls from spreadsheet in .ods, .xls, or .xslx format and wirite them in the heating file specified by -f/–heating-file. Overwrites all rooms and walls in the heating file. The building name is default or must be given by -b/–building. The program exits after importing the spreadsheet data.

--timestep

the model timestep in s[1].

Default: 1

plot

plot AUSTAL output data

A simple plot for a quick overview (click to enlarge) plotcontour

austaltools plot [-h] [-s [STDVs]] [--scale [VALUE]] [-b] [-l] [-c COLORMAP]
                 [-k {contour,grid}] [-p [FILE]] [-f]
                 DATA

Positional Arguments

DATA

data file to plot.

Named Arguments

-s, --stdvs

hash areas where the data are not significant. Sigingicant is defined as larder than STDVs times the standard deviation caculated by austal. If missing, STDVs defaults to 1.0.

Default: 0.0

-b, --no-buildings

do not show the buildings defined in config file

Default: True

-l, --low-colors

use only few discrete colors for better print results

Default: False

-c, --colormap

name of colormap to use. Defaults to “YlOrRd”

Default: 'YlOrRd'

-k, --kind

Possible choices: contour, grid

choose kind of display. contour produces filled contours, grid produces coloured grid cells. Defaults to contour

Default: 'contour'

-p, --plot

save plot to a file. If FILE is “-” the plot is shown on screen. If FILE is missing, the file name defaults to the data file name with extension png

-f, --force

force overwriting plotfile if it exists.

Default: False

advanced options

--scale

Max value of the colour scale in plotted value units. Default is autoscale.

simple

simple-to-use interface to the most basic funtionality of austaltools:the creation of input files for simulations

austaltools simple [-h] LAT LON NAME

Positional Arguments

LAT

Center position latitude

LON

Center position longitude

NAME

Stem for file names.

steepness

Plot AUSTAL topography steepness

austaltools steepness [-h] [-g ID | -t FILE] [-b] [-l] [-c COLORMAP]
                      [-k {contour,grid}] [-p [FILE]] [-f]

Named Arguments

-g, --grid

ID (number) of the grid to evaluate. Defaults to 0

Default: 0

-t, --topo

Topography file to read instead of the AUSTAL topography files.

-b, --no-buildings

do not show the buildings defined in config file

Default: True

-l, --low-colors

use only few discrete colors for better print results

Default: False

-c, --colormap

name of colormap to use. Defaults to “YlOrRd”

Default: 'YlOrRd'

-k, --kind

Possible choices: contour, grid

choose kind of display. contour produces filled contours, grid produces coloured grid cells. Defaults to contour

Default: 'contour'

-p, --plot

save plot to a file. If FILE is “-” the plot is shown on screen. If FILE is missing, the file name defaults to the data file name with extension png

-f, --force

force overwriting plotfile if it exists.

Default: False

terrain

generate terrain input for AUSTAL

austaltools terrain [-h] (-L LAT LON | -G X Y | -U X Y) [-c CODE] [-e KM]
                    [-s CODE]
                    NAME

Positional Arguments

NAME

file name to store data in.

Named Arguments

-L, --ll

Center position given as Latitude and Longitude, respectively. This is the default.

-G, --gk

Center position given in Gauß-Krüger zone 3coordinates: X = Rechtswert, Y = Hochwert.

-U, --utm

Center position given in UTM Zone 32Ncoordinates: X = easting, Y = northing.

-c, --crs

Possible choices: ut, gk

coordinate reference system of the output: gk: Gauss-Krüger (zone 3), ut: UTM (zone 32U). Defaults to ‘ut’

Default: 'ut'

-e, --extent

extent of the extracted area in km (side length of the sqare)Defaults to 5.0

Default: 5.0

-s, --source

code for the source digital elevation model (DEM). Defaults to ‘GTOPO30’

Default: 'GTOPO30'

transform

transfrom coordinates into other projections

austaltools transform [-h] [-L LAT LON | -G X Y | -U X Y | -D NUMBER |
                      -W NUMBER] [-M x y] [-f]

Named Arguments

-L, --ll

Center position given as Latitude and Longitude, respectively. This is the default.

-G, --gk

Center position given in Gauß-Krüger zone 3coordinates: X = Rechtswert, Y = Hochwert.

-U, --utm

Center position given in UTM Zone 32Ncoordinates: X = easting, Y = northing.

-D, --dwd

Weather station position with German weather service (DWD) ID NUMBER

-W, --wmo

Postion of weather station with World Meteorological Organization (WMO)station ID NUMBER

-M, --model

Transform position given in model coordinats x and y (relative to the model origin) into geographic coordinates.

-f, --float

Print UTM and Gauss-Krüger coordinates as floating-point numbers with decimals for more precision (Note that using floating-point numbersfor the reference coordinateswill cause AUSTAL to crash).

Default: False

weather

Extract atmospheric time series for AUSTAL from various sources

austaltools weather [-h] (-L LAT LON | -G X Y | -U X Y | -D NUMBER |
                    -W NUMBER) [-s CODE] [-y YEAR] [-e METERS] [-p]
                    [--class-scheme {all,kms,kmo,k2o,pts,kmc,pgc}]
                    [--inter-variant {weighted,nearest,mean}]
                    [--read-extracted FILE] [-x]
                    [--wind-variant {fixed_057,fixed_010,model_mean,model_uv10,model_fsr}]
                    [--z0 Z0]
                    [NAME]

Positional Arguments

NAME

file name to store data in.

Named Arguments

-L, --ll

Center position given as Latitude and Longitude, respectively. This is the default.

-G, --gk

Center position given in Gauß-Krüger zone 3coordinates: X = Rechtswert, Y = Hochwert.

-U, --utm

Center position given in UTM Zone 32Ncoordinates: X = easting, Y = northing.

-D, --dwd

Weather station position with German weather service (DWD) ID NUMBER

-W, --wmo

Postion of weather station with World Meteorological Organization (WMO)station ID NUMBER

-s, --source

Possible choices: ERA5, CERRA, HOSTRADA, DWD

select the source for the weather data. Known CODE values are ERA5 CERRA HOSTRADA DWD Defaults to ERA5

Default: 'ERA5'

-y, --year

year of interest [2003]

-e, --elevation

surface elevation. An approximate value is sufficientonly allowed with -L, -G, -U.

-p, --precip

add precipitation columns to output file

Default: False

advanced options

--class-scheme

Possible choices: all, kms, kmo, k2o, pts, kmc, pgc

Choose the method how stability classesare derived from the weather data.Possible values: [‘all’, ‘kms’, ‘kmo’, ‘k2o’, ‘pts’, ‘kmc’, ‘pgc’]. [‘all’]

  • kms: Klug/Manier scheme (after VDI 3782 Part 6, issued Apr 2017) calculated from date, time, wind speed, total cloud cover, and cloud type of the lowest cloud layer

  • kmo: Klug/Manier scheme (after VDI 3782 Part 1, issued 1992) calculated from date, time, wind speed, total cloud cover,and cloud type of the lowest cloud layer

  • k2o: Klug/Manier scheme (after VDI 3782 Part 6, issued Apr 2017) calculated from date, time, wind speed, total cloud cover,and cloud base height (alternativelycloud type of the lowest cloud layer)

  • pts: Pasquill/Turner scheme (after EPA-454/R-99-005, issued 2000) calculated from date, time, wind speed, total cloud cover, and cloud type of lowest cloud layer

  • kmc: classify the model-derived Obukhovlength into stability classes using the class boundaries of the Klug/Manier scheme (after TA-Luft, 2021 issued 1992)

  • pgc: classify the model-derived Obukhovlength into stability classes using the class boundaries of the Pasquill/Gifford stability classes (scraped from Golder, 1972)

Default: 'all'

--inter-variant

Possible choices: weighted, nearest, mean

Controls the interpolation of gridded data to the position specified. Possible values: [‘weighted’, ‘nearest’, ‘mean’]. [‘weighted’]

  • nearest: take model values from nearestgrid point

  • mean: arithmetic mean of the model values at the three nearest grid poinst

  • weighted: barycentric mean (weighted by distance) of the model values at the three nearest grid poinst

Default: 'weighted'

--read-extracted

Save time by re-reading extracted weather data form a saved file.

-x, --write-extracted

write full extracted weather data to an extra file

Default: False

--wind-variant

Possible choices: fixed_057, fixed_010, model_mean, model_uv10, model_fsr

Controls how the 10-m wind is calculatedfrom ERA5 reanaysis data.possible values: [‘fixed_057’, ‘fixed_010’, ‘model_mean’, ‘model_uv10’, ‘model_fsr’]. [‘model_uv10’]

  • fixed_057: from friction velocity using a fixed roughness length \(z_0\) = 0.57 m

  • fixed_010: from friction velocity using a fixed roughness length \(z_0\) = 0.10 m

  • model_fsr: from friction velocity using the instant forecast surface roughness from the model for each hour

  • model_mean: from friction velocity using the mean forecast surface roughness from the model, averaged over the whole data period

  • model_uv10: use the 10-m wind provided by the model

Default: 'model_uv10'

--z0

roughness length at the position of the measurement used for calculation of the effective anemometer height. Overrides the value provided by the data source. Ignored if value is None. [None]

volout

Plot building volumes

Example plot of a buildings volume plot (click to enlarge) plotvolout

austaltools volout [-h] [-k {default}] [-p [FILE]] [-g GRID | -f FILE]
                   [-c {fit,center,no}] [-a ANGLE] [--color COLOR]

Named Arguments

-k, --kind

Possible choices: default

style of volume plot [‘default’])]

Default: 'default'

-p, --plot

save plot to a file. If FILE is “-” the plot is shown on screen. If FILE is missing, the file name defaults to the data file name with extension png

-g, --grid

Number of the grid for which to plot the building volumes [1])].

Default: 1

-f, --file

Name of the file to read [None])].

-c, --clip

Possible choices: fit, center, no

Zoom level for plotting: n - “no”: view full gridn - “center”: zoom to grid centern - “fit”: zoom closest to buildingsnDefaults to [‘fit’])].

Default: 'fit'

-a, --angle

viewing angle:n - N, E, S, W: side view from north, east, south, westn - NW, SW, SE, NE: isometric view from … n - 0…360: Perspective view from direction (geographic degrees, clockwise from north)n - AZI,ELE[,FL]: comma-sepatrated tuple of view-from direction and elevation, and optionally focal length (focal length of 1.0 corresponds to 90° field of view, defaults to 0.5 if absent)nDefault is [‘SW’])].

Default: 'SW'

--color
color of the buidlings as

  • color name or html color code (a darker shade is used for the edges

  • two comma-separated color names or html color codes (used for sides and egdes)

Html color codes in the form #rrggbb. Defaults to [‘sienna’])].

Default: 'sienna'

windfield

Plot wind field

Example plot of a windfield (click to enlarge) plotwindfield

austaltools windfield [-h] [-b] [-c COLORMAP] [-s] [-g GRID] (-a ASL |
                      -z AGL | -l NUMBER) (-t "YYY-MM-DD HH:MM:SS" |
                      -w SPEED DIR AK | -W U V AK) [-p [FILE]] [--z0 Z0]
                      {stream,stream-color,arrows,arrows-color,barbs,barbs-color}

Positional Arguments

style

Possible choices: stream, stream-color, arrows, arrows-color, barbs, barbs-color

style of wind field plot

Named Arguments

-b, --no-buildings

do not show the buildings defined in config file

Default: True

-c, --colormap

name of colormap to use. Defaults to “plasma”

Default: 'plasma'

-s, --shade

add hillshading in background

Default: False

-g, --grid

number of grid to plot. Defaults to 0

Default: 0

-a, --altitude

display horizontal slice at ASL meters above sea level. Defaults to None

-z, --height

display horizontal slice at height AGT above ground level. Defaults to None

-l, --level

display horizontal slice at model level NUMBER (0-based). Defaults to None

-t, --time

display windfield corresponding to the wind and stability from akterm for the time given by YYY-MM-DD HH:MM:SS. Defaults to None

-w, --wind

display windfield corresponding to the wind SPEED, DIR`ection and stability class `AK. Defaults to None

-W, --wind-vector

display windfield corresponding to the wind vector (U, V) and stability class AK. Defaults to None

-p, --plot

save plot to a file. If FILE is “-” the plot is shown on screen. If FILE is missing, the file name defaults to the data file name with extension png

advanced options

--z0

roughness length at the position of the measurement used for calculation of the effective anemometer height. Overrides the value provided by the data source. Ignored if value is None. [None]

windrose

Plot wind rose

Example plot of a windrose classified by wind speed quantiles (click to enlarge) plotwindrose

austaltools windrose [-h] [-k {default,star,step,ring}] [-n SECTORS]
                     [-s {beaufort,2ms,quantile,stability,halfyear,season}]
                     [-c COLORMAP] [-p [FILE]] [-w WEATHER]

Named Arguments

-k, --kind

Possible choices: default, star, step, ring

style of wind field plot [‘default’])]

Default: 'default'

-n, --sectors

number of sectors to plot [‘12’])]

Default: '12'

-s, --scale

Possible choices: beaufort, 2ms, quantile, stability, halfyear, season

How to classify the values [‘beaufort’]:

  • beaufort: wind speed in beaufort

  • 2ms: wind speed in steps of 2 m/s

  • quantile: wind speed quantiles

  • stability: stability class

  • halfyear: summer/winter half year

  • season: meteorological season

Default: 'beaufort'

-c, --colormap

name of colormap to use. The default depends on -k.

-p, --plot

save plot to a file. If FILE is “-” the plot is shown on screen. If FILE is missing, the file name defaults to the data file name with extension png

-w, --weather

name of the weather data file toread. If this option is not given orNone, the name file is determined from austal.txt [None])].