Workflow¶
This chapter describes various possible workflows with LADiM, from simple usage
to developing. Some terminology may be useful. An installed LADiM, has been
installed by python setup.py install
in the LADiM root directory, either
system-wide by sudo or personal by using the --prefix
-option,
see Installation. This is typical a working stable version in a
usable state.
Unmodified use¶
The simplest workflow is to simply use the installed LADiM. Use a work
directory, copy and modify a ladim1.yaml
file to point to your input files
and adjust the simulation time and other settings. Run the simulation by the
command ladim1.
The configuration file can be renamed and saved to make the model simulation reproducible. To run LADiM with a named configuration file, give the file name as a command line argument to the ladim command.
Possible complication: if you are in a python2 environment ,,,
Modify the IBM¶
The IBM modules can be very different, with very configuration requirements. The configuration system is therefore not able to configure all details of the IBMs. Consequently, IBMs are the most likely modules where the code has to be modified.
To modify an IBM, copy the file to your working directory. Modify the
ibm -> ibm-module
setting in the configuration file to point to the
local module. Thereafter, the installed ladim command should work properly.
A totally new IBM, for another species perhaps, can be developed locally in
the work directory and activated in the same way. The IBM
module description documents what an IBM
class should make available.
An example of this is the minimal IBM in the examples/killer
directory.
As the new IBM matures, it should be included in the ladim/ibms
directory.
Modify other modules¶
The code of other modules may be modified in a slightly different way.
Copy the module to the working directory and modify it as above.
To activate it, copy the main ladim script script/ladim
to the
working directory and modify the import statement to point to the
local module. To make sure that the correct script is executed, run the
simulation with the command ./ladim
.
A common use case may be to develop new gridforce
modules to work
with output from different ocean models or idealized settings. The
gridforce
description specifies the necessary public attributes and
methods for the Grid
and Forcing
classes.
The logo example, examples/logo
has a minimal idealized gridforce
-module.
In future, the LADiM distribution may contain a collection of different
gridforce modules and the choice be available by the configure mechanism
in the same manner as for the IBM
.
The trick of using a local ladim
-script may be use for other modifications
of as well.
Maintenance and further development¶
For develop work on LADiM it is important to not mess up the stable installed
version. This can be done by virtualization. Use a separate git
branch for
the development and a separate conda
or virtualenv
environment.
The conda solution is described below.
The git
part is set up by:
git clone https://github.com/bjornaa/ladim1.git
cd ladim
git branch mydevelop
git checkout mydevelop
Use conda env list
to find the environments, find one with python 3, say
py36
and clone it locally, for instance in $HOME/conda/envs
:
conda create -p $HOME/myenv --clone py36
source activate $HOME/myenv
python setup.py install
This installs the developing version in the myenv
-environment.
Do a python setup install
after every change before running LADiM.
To get back to the stable environment do:
git add ...
git commit ...
git checkout master
source deactivate
Instead of source deactivate
it is enough to simply kill the working window.
The next time, it is easier. It is enough to write:
git checkout mydevelop
source activate $HOME/myenv
If the development is a general improvement or important addition to the standard LADiM a pull request should be sent to github so that it can be included in the stable version.