Package: lagtraj
lagtraj Lagragian simulations trajectoriesProducing a Lagrangian forcingThere are three steps to making forcing profiles with lagtraj:Download source data domainfor a given
date-range (small for Eulerian simulations, big for Lagrangian)Produce trajectoryExtract forcing
profilesalong the trajectory (with optional conversion to target a specific LES/GCM
model)The guide below first details how to install lagtraj and then guides your each
of these three steps.0. Getting startedInstalling lagtrajThe most recent tagged version oflagtraj(and all its dependencies) can be
installed with pip directly from pipy:$>python-mpipinstalllagtrajNOTE: if you are intending to modifylagtrajyourself you should check out
thedevelopment notes.lagtrajrequires Python 3 and is developed and tested withpython3.8(in
that we aim to follow the recommendations ofNEP29) but later
versions should work too (it may work with earlier versions too).Once installed alllagtraj's commands are available from any directory
and the follow the pattern$>python-mlagtraj.<command>lagtraj input and outputlagtrajstores everything (both source data andinput definitionsdescribing how domains, trajectories and forcings are set up) in adata
directory(by default this will bedata/relative to wherelagtrajis
invoked). The directory structure is as follows:data
├──domains
│├──eurec4a_circle.yaml
│└──eurec4a_circle_data
│├──an_model_2020-01-01.nc
│:
│└──fc_single_2020-01-03.nc
├──forcings
│├──eure4a_20200103_lag_testcase.yaml
│└──eure4a_20200103_lag_testcase.nc
└──trajectories├──eure4a_20200103_lag_testcase.yaml└──eure4a_20200103_lag_testcase.ncThenameof each domain/trajectory/forcing insidelagtrajwill be the
full filename without the.yaml-extension. E.g. the domain definition indomains/eurec4a_circle.yamlwill have the nameeurec4a_circleinsidelagtraj.You can either make your own domain/forcing/trajectory definition (these
are stored in yaml-files) by creating a yaml-file in the relevant
directory or use one thatlagtrajcomes with. You can list the
input-defintions bundled with your copy oflagtrajby running the
following command:$>python-mlagtraj.input_definitions.examplesWhich will printThefollowingdomain/forcing/trajectorydefinitionsarecurrentlyincluded
withlagtraj:

lagtraj://├──domains│├──drydown_cardington_local│├──eurec4a_circle│└──eurec4a_north_atlantic├──forcings│├──drydown_cardington_20200420_00_eul│├──eurec4a_campaign_eulerian│├──eurec4a_20200128_first│├──eurec4a_20200202_first_short_press│├──eurec4a_20200202_first_short│├──eurec4a_20200202_first
...1. Making source data availablelagtrajis based around making all data required for interpolation,
integration and forcing calculation available before trajectories and forcings
are calculated. This was done to reduce the number of data requests required
to the data storage backends (e.g. ECMWF), but does mean thatthe expected
spatial extent that a trajectory will reach must been known before performining
a trajectory integration, otherwiselagtrajwill issue a warning when the
edge of the available domain is reached.Either create your own domain definition indata/domains/<domain_name>.yamland run$>python-mlagtraj.domain.download<domain_name><start_date><end_date>Or use one of the domain definitions included withlagtraj(e.g.eurec4a_circle$>python-mlagtraj.domain.downloadlagtraj://eurec4a_circle<start_date><end_date>the<start_date>and<end_date>should be formatted asYYYY/MM/DD, e.g.2020/02/01for the 2nd of February 2020.An optional flag--retry-rate <num_minutes>causeslagtrajto continue
retrying download of submitted data requests everynum_minutesminutes until
all data has been downloaded. Every time this command is run it will attempt to
download only data not yet downloaded.2. Producing a trajectoryOnce you have downloaded the required domain data you can either create
a trajectory definition indata/trajectories/<trajectory_name>.yamland run$>python-mlagtraj.trajectory.create<trajectory_name>Or use one of the trajectory definitions included withlagtraj(e.g.eurec4a_20200202_first_short$>python-mlagtraj.trajectory.createlagtraj://eurec4a_20200202_first_shortThe created trajectory will be stored indata/trajectories/<trajectory_name>.nc.3. Producing forcing profilesTo produce forcings you need to create a forcing definition indata/forcings/<forcing_name>.yamland run$>python-mlagtraj.forcings.create<forcing_name>[--conversion<conversion_name>]Or use one of the forcing definitions included withlagtraj(e.g.eurec4a_20200202_first_short)$>python-mlagtraj.forcings.createlagtraj://eurec4a_20200202_first_short[--conversion<conversion_name>]Forcing profiles conversion (targeting a specific GCM/LES)When creating forcings it might be desirable to target a specific LES
(Large-Eddy Simulation) model or GCM (Global Circulation Model) by
converting the forcings to a specific format and setting parameters
specific to the model being targeted. This can be achieved by using the--conversionflag and providing aconversion_name.lagtrajcurrently
comes bundled with functionality to target theKPTLES anddephyLES format.Conversion parameters are defined in a yaml-files similarly to how domain,
trajectory and forcings definitions are stored, with one important difference:
conversion definition files are associated with a specific forcing definition
file (i.e. each forcing conversion definition points to only one specific
forcing definition).lagtrajcomes bundled with definitions for how to do
forcing conversion with sensible defaults that you can modify for each forcing
you wish to create.To set the parameters for a conversion identifed by the namekptfor
converting a forcing with nameforcing_nameyou should create a file indata/forcings/<forcing_name>.<conversion_name>.yaml. Running a conversion
will the convertdata/forcings/<forcing_name>.ncand save todata/forcings/<forcing_name>.<conversion_name>.nc.$>python-mlagtraj.forcings.create<forcing_name>[--conversion<conversion_name>]Instead of creating a conversion definition starting from an empty file you can
bootstrap the process by using the default parameters for a given target model
included with lagtraj. This is achieved by using thelagtraj://-prefix when
choosing the conversion name. E.g. to create the forcing namedeurec4a_20200202_first_shortbundled withlagtrajand have it converted to
thedephyformat with the default parameters you would run$>python-mlagtraj.forcings.createlagtraj://eurec4a_20200202_first_short--conversionlagtraj://dephyThis will create the un-converted forcing indata/forcings/eurec4a_20200202_first_short.nc, the converted one indata/forcings/eurec4a_20200202_first_short.dephy.ncand the default conversion definition
for targetingdephywill be copied todata/forcings/eurec4a_20200202_first_short.dephy.yaml. You can then modify
the forcing parameters (for example change the number of levels) by editingdata/forcings/eurec4a_20200202_first_short.dephy.yamland rerunning the
forcing creation with your local copy of the conversion definition (note the
absence of thelagtraj://prefix):$>python-mlagtraj.forcings.createlagtraj://eurec4a_20200202_first_short--conversiondephyYou are of course welcome to rename the conversion however you like if for
example you'd like to have multiple different converted version of the same
forcings file.Contributing and commentsIf you have any comments/questions/issues aboutlagtrajplease feel free toopen an issueor have a
look indocs/developing.mdwhere we have added some notes
on how to get started. All contributions are very welcome!