farn

farn is an n-dimensional case generator.

Its primary design goal is to parameterize and execute simulation cases. However, at its core, farn is use-case agnostic and can support a wide spectrum of applications.

The name ‘farn’ is inspired by the Barnsley fractal

farn

• runs the sampling of the design space (sampling strategies cover fixed, linSpace, uniformLHS)
• generates the corresponding case folder structure
• copies arbitrary files from a template folder to case folders
• creates case specific parameter files in case folders
• executes user-defined shell command sets in case folders
• builds case specific OSP (co-)simulation files
• runs simulation cases as batch process

Installation

pip install farn

farn requires the following two (sub-)packages:

1. dictIO: foundation package, enabling farn to handle configuration files in dictIO dict file format.
2. ospx: extension package, enabling farn to generate OSP (co-)simulation files.

However, both get installed automatically with farn (just pip install farn and you're done).

Usage Example

farn provides both an API for use inside Python as well as a CLI for shell execution of core functions.

Reading a farnDict file and creating the corresponding case folder structure:

from farn import run_farn

run_farn('farnDict', sample=True, generate=True)

The above task can also be invoked from the command line, using the 'farn' command line script installed with farn:

farn farnDict --sample --generate

For more examples and usage, please refer to farn's documentation.

Further, the farn-demo repository on GitHub is an excellent place for a jumpstart into farn. Simply clone the farn-demo repository to your local machine and click through the demos and related READMEs, by recommendation in the following sequence:

README in root folder -> guides you through installation of farn
\ospCaseBuilder Demo (see README in ospCaseBuilder folder)
\farn Demo (see README in farn folder)
\importSystemStructure  Demo (see README in importSystemStructure folder)

File Format

A farnDict is a file in dictIO dict file format used with farn.

For a documentation of the farnDict file format, see File Format in farn's documentation on GitHub Pages.

For a detailed documentation of the dictIO dict file format used by farn, see dictIO's documentation on GitHub Pages.

Development Setup

1. Install Python 3.9 or higher, i.e. Python 3.10 or Python 3.11

2. Update pip and setuptools:

   python -m pip install --upgrade pip setuptools
   

3. git clone the farn repository into your local development directory:

   git clone https://github.com/dnv-opensource/farn path/to/your/dev/farn
   

4. In the farn root folder:

   Create a Python virtual environment:

   python -m venv .venv
   

   Activate the virtual environment:

   ..on Windows:

   > .venv\Scripts\activate.bat
   

   ..on Linux:

   source .venv/bin/activate
   

   Update pip and setuptools:

   (.venv) $ python -m pip install --upgrade pip setuptools
   

   Install farn's dependencies:

   (.venv) $ pip install -r requirements-dev.txt
   

   This should return without errors.

   Finally, install farn itself, yet not as a regular package but as an editable package instead, using the pip install option -e:

   (.venv) $ pip install -e .
   

5. Test that the installation works (in the farn root folder):

   (.venv) $ pytest .
   

Meta

Copyright (c) 2024 DNV open source

Frank Lumpitzsch – @LinkedIn – frank.lumpitzsch@dnv.com

Claas Rostock – @LinkedIn – claas.rostock@dnv.com

Seunghyeon Yoo – @LinkedIn – seunghyeon.yoo@dnv.com

Distributed under the MIT license. See LICENSE for more information.

https://github.com/dnv-opensource/farn

Contributing

1. Fork it (https://github.com/dnv-opensource/farn/fork)
2. Create your branch (git checkout -b myBranchName)
3. Commit your changes (e.g. git commit -m 'place a descriptive commit message here')
4. Push to the branch (e.g. git push origin myBranchName)
5. Create a new Pull Request in GitHub

For your contribution, please make sure you follow the STYLEGUIDE before creating the Pull Request.