`cosmic-settings.json` file explained¶

This file contains all of the settings information for every setting available in COSMIC. We write all of this information in a single centralised JSON file and this can then be used to populate all other parts of the COSMIC defaults and documentation.

In this guide let’s take a look at the JSON schema for the file so it is clear how to add new settings or options.

File structure¶

The high level structure of the file looks something like this:

{
    "category": "CATEGORY NAME",
    ...,
    "settings": [
        ...,
        {
            "name": "SETTING NAME",
            ...,
            "options": [
                ...,
                {
                    "name": "OPTION NAME",
                    ...,
                },
                ...
            ]
        }
        ...
    ]

where the ... lines are extra parameters that we’re not showing here (but do show below). You can see there are a series of categories (e.g. Sampling, BSE), settings (e.g. sampling_method, alpha1) and options (e.g. independent or multidim) in the file. I’m going to assume you’ll not be creating new categories but it should be fairly similar to new settings or options - let’s go into those two in more detail.

Schema for a setting¶

Here is a list of the potential parameters in the setting object:

Schema for a setting¶
Field name	Type	Use/meaning	Optional?
name	string	Name of the setting	Required
description	string	Explanation of the setting	Required
type	string	What type of input this setting uses (one of ‘number’ - ‘string’ - ‘dropdown’ - ‘checkbox’)	Required
options-preface	string	Extra information about the options (on docs only shown after expanding options)	Optional
options	array	List of option objects
settings-section	string	Title of a new subsection of settings (starts immediately before this setting)	Optional
settings-section-description	string	Description of this subsection of settings	Optional

In general any long strings (e.g. in the description or options-preface) you can use full HTML tags and they will be rendered (e.g. bold some text, link a paper). See below if you’re not familiar with this! It may be simplest to just look at some existing settings if you’re unsure.

Schema for an option¶

And here’s the same sort of thing for an option object, several of which comprise the setting["options"] array in each setting.

Schema for an option¶
Field name	Type	Use/meaning	Optional?
name	string/number	Name of the option	Required
description	string	Explanation of the option	Required
default	bool	Whether this is the default option. For settings with type=”checkbox” can have multiple defaults. If this field is missing it is assumed false.	Optional

Quick HTML cheatsheet¶

As noted above, if you want to bold some text or link a paper in your setting/option descriptions then here’s some quick HTML tags for doing that. Once the options are converted into files these tags will get stripped out. You can also add inline maths symbols following the last line (Notice the escaping of every backslash - i.e. two backslashes needed).

Before (HTML code)¶

<b>This text is bold</b>
<i>This text is italic</b>
Here is <code>some code</code>
This line is broken<br>by a new line
<a href="https://google.com">This bit</a> is a link
Here's a fancy equation \\( y = m x + c \\)

After (rendered results)¶

These will render to approximately the following

This text is bold

This text is italic

Here is some code

This line is broken

by a new line

This bit is a link

Here’s a fancy equation \(y = m x + c\)